@ultimat3/storage 1.1.0 → 2.0.0

package/src/errors.ts

@@ -2,7 +2,7 @@
 // rejected upload must tell the caller which constraint fired and where that constraint is
 // configured, or the caller retries the same bytes forever.
 
-import { errorDocsUrl, registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { errorDocsUrl, registerErrorCodes, renderThrowable, UltimateError } from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const STORAGE_OWNED_ERROR_CODES = [
@@ -12,14 +12,23 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_TOO_LARGE',
   'X_STORAGE_TYPE_REJECTED',
   'X_STORAGE_CHECKSUM_MISMATCH',
+  'X_STORAGE_URL_INVALID',
+  'X_STORAGE_URL_EXPIRED',
+  'X_STORAGE_ORG_MISMATCH',
+  'X_STORAGE_UPLOAD_FAILED',
+  'X_STORAGE_DELETE_FAILED',
+  'X_STORAGE_LIST_FAILED',
+  'X_STORAGE_QUARANTINED',
 ] as const;
 
 /**
  * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `storageNotImplemented()` throws it and this package
  * keeps no title for it — one code, one owner, one title, or the two copies drift apart in silence.
  * `X_IMAGE_UNSUPPORTED` / `X_IMAGE_DECODE_FAILED` are core's too and surface unwrapped (`image.ts`).
+ * `X_ENV_MISSING` is core's for the same reason: an unset `STORAGE_SIGNING_SECRET` outside
+ * development is a missing environment variable, not a storage concept needing its own code.
  */
-export const STORAGE_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
+export const STORAGE_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED', 'X_ENV_MISSING'] as const;
 
 /** Every code storage can throw through `StorageError`: the owned ones plus the borrowed one. */
 export const STORAGE_ERROR_CODES = [
@@ -37,6 +46,13 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_TOO_LARGE: 'payload exceeds the upload size limit',
   X_STORAGE_TYPE_REJECTED: 'content type is not allowed for this upload',
   X_STORAGE_CHECKSUM_MISMATCH: 'bytes do not match the declared checksum',
+  X_STORAGE_URL_INVALID: 'signed URL does not match its signature',
+  X_STORAGE_URL_EXPIRED: 'signed URL is past its expiry',
+  X_STORAGE_ORG_MISMATCH: 'object key belongs to another org',
+  X_STORAGE_UPLOAD_FAILED: 'the signed upload was refused',
+  X_STORAGE_DELETE_FAILED: 'the object could not be deleted',
+  X_STORAGE_LIST_FAILED: 'the objects could not be listed',
+  X_STORAGE_QUARANTINED: 'the object is still in quarantine',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -113,6 +129,33 @@ export const tooLarge = (key: string, bytes: number, maxBytes: number): StorageE
     meta: { key, bytes, maxBytes },
   });
 
+/**
+ * The SERVER-side `put()` ceiling — a different fact from the policy limit `tooLarge` reports.
+ * `put()` buffers, so a body past the ceiling is heap growth whose size the sender chooses: the
+ * pod is OOM-killed and the caller sees a dropped connection instead of a refusal. Same CODE as
+ * the policy limit, because it is the same answer to the same question (413, "too big"), and a
+ * different `fix`, because raising `uploadPolicy` does not raise this one.
+ *
+ * `bytes` is what the disk had measured when it stopped, which for a stream is a floor rather
+ * than the body's real length — the point of stopping is not reading the rest.
+ */
+export const putTooLarge = (
+  disk: string,
+  key: string,
+  bytes: number,
+  maxBytes: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `"${key}" measured ${bytes}B against the ${disk} disk's put ceiling of ${maxBytes}B, and put() buffers the whole body`,
+    fix:
+      `send it direct with grantUpload({ disk, orgId, request }) instead of put(), or raise the ceiling: ` +
+      (disk === 's3'
+        ? `s3Driver({ bucket, maxPutBytes: ${bytes} })`
+        : `localDriver({ root, maxPutBytes: ${bytes} })`),
+    meta: { disk, key, bytes, maxBytes },
+  });
+
 /** The declared type is not on the allowlist at all. */
 export const contentTypeNotAllowed = (
   key: string,
@@ -143,6 +186,130 @@ export const checksumMismatch = (key: string, declared: string, actual: string):
     meta: { key, declared, actual },
   });
 
+/**
+ * A signed request that does not match what was signed — a tampered constraint, a URL outside
+ * the mounted base, a method the grant never covered, a header the signature contradicts.
+ * ONE code for all of them on purpose: telling a forger which half of the tuple they got wrong
+ * is an oracle, and `meta.reason` is there for the server's own log.
+ */
+export const signedUrlRejected = (reason: string, detail: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_URL_INVALID',
+    cause: `the signed request was rejected as ${reason}: ${detail}`,
+    fix: 'mint a fresh one with grantUpload({ disk, orgId, request }) and send it unedited — every constraint is inside the signature',
+    meta: { reason, detail },
+  });
+
+export const signedUrlExpired = (key: string, detail: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_URL_EXPIRED',
+    cause: `the signed request for "${key}" ${detail}`,
+    fix: 'call grantUpload({ disk, orgId, request, expiresInMs }) again — a longer expiresInMs widens the window the signature grants',
+    meta: { key, detail },
+  });
+
+/**
+ * A delete the provider REFUSED — a denied `s3:DeleteObject`, a throttle, an expired credential,
+ * a read-only mount. Deleting an absent key stays idempotent and never reaches here; everything
+ * else does, because the alternative shipped for a year: `.catch(() => undefined)` turned 200
+ * denied deletes into 200 successes, and an erasure sweep reported data gone that was still there.
+ *
+ * The `fix` is the driver's, not this factory's: the executable command that reproduces the
+ * refusal with the provider's own words differs per disk, and a generic one is a round trip.
+ */
+export const deleteFailed = (
+  disk: string,
+  key: string,
+  error: unknown,
+  fix: string,
+): StorageError => {
+  const reason = renderThrowable(error);
+  return new StorageError({
+    code: 'X_STORAGE_DELETE_FAILED',
+    cause: `disk "${disk}" refused DELETE "${key}": ${reason}`,
+    fix,
+    meta: { disk, key, reason },
+  });
+};
+
+/**
+ * A listing the disk REFUSED — a denied `s3:ListBucket`, a throttle, an expired credential, a root
+ * this process cannot read. Exactly `deleteFailed`'s shape and for exactly its reason: an empty
+ * page and an unreadable one are indistinguishable to a caller, and `sweepOrphans` walks `list()`,
+ * so a swallowed refusal reports "no orphans" for a prefix nothing could see — the false-erasure
+ * report the `delete()` fix already closed one call to the left.
+ *
+ * A root that does not exist yet is NOT this: a disk nobody has written to is honestly empty, and
+ * both drivers answer it with an empty page.
+ *
+ * The `fix` is the driver's, for `deleteFailed`'s reason: the command that reproduces the refusal
+ * with the disk's own words differs per driver, and a generic one costs a round trip.
+ */
+export const listFailed = (
+  disk: string,
+  prefix: string,
+  error: unknown,
+  fix: string,
+): StorageError => {
+  const reason = renderThrowable(error);
+  return new StorageError({
+    code: 'X_STORAGE_LIST_FAILED',
+    cause: `disk "${disk}" refused to list "${prefix === '' ? '(the whole disk)' : prefix}": ${reason}`,
+    fix,
+    meta: { disk, prefix, reason },
+  });
+};
+
+/**
+ * A key still under the quarantine prefix. The framework never scans bytes — that is the app's
+ * job — so the only thing it can enforce is that nothing leaves quarantine without the app
+ * saying so, which is what `promoteAttachment` refusing this key means.
+ */
+export const quarantined = (key: string, orgId: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_QUARANTINED',
+    cause: `"${key}" is still under the quarantine prefix, so nothing has cleared it for use`,
+    fix: `scan the bytes, then releaseQuarantine({ disk, key: '${key}', orgId: '${orgId}' }) — promote the key it returns`,
+    meta: { key, orgId },
+  });
+
+/** The key is well-formed and unforged, and still belongs to somebody else. */
+export const orgMismatch = (key: string, orgId: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_ORG_MISMATCH',
+    cause: `key "${key}" is not inside org "${orgId}"`,
+    fix: `build it with scopedKey('${orgId}', ...parts), and pass the ACTOR's org as orgId — never one read off the request`,
+    meta: { key, orgId },
+  });
+
+/** The client half: the disk answered the presigned PUT with something other than 2xx. */
+export const uploadFailed = (path: string, status: number, detail: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_UPLOAD_FAILED',
+    cause: `PUT ${path} answered ${status}: ${detail === '' ? 'no body' : detail}`,
+    fix: 'call uploadFile({ file, grant }) again for a fresh grant; a 4xx here is the constraint named in the body, not a transport fault',
+    meta: { path, status, detail },
+  });
+
+/**
+ * The local disk fell back to the shipped dev signing key outside development.
+ *
+ * That literal is published in this repo, so anyone holding it can mint a signed `PUT` for any
+ * key — including another org's — with `maxBytes` and `contentType` of their choosing, and
+ * `acceptSignedUpload` trusts the signed constraints over the app's `uploadPolicy`. A 200KB
+ * avatar grant becomes an unlimited upload of any type. Refused at construction, not at the
+ * first `signedUrl()`: a process that cannot sign safely must not finish booting.
+ */
+export const signingSecretMissing = (environment: string): StorageError =>
+  new StorageError({
+    code: 'X_ENV_MISSING',
+    // The environment names what `resolveEnvironment()` resolved, which may have come from
+    // NODE_ENV — naming ULTIMATE_ENV here reported a variable the process never set.
+    cause: `the local disk has no usable signing secret (no signingSecret option, and STORAGE_SIGNING_SECRET is unset, empty or the published development key) and the resolved environment is "${environment}", so it would sign URLs with the shipped development key`,
+    fix: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
+    meta: { key: 'STORAGE_SIGNING_SECRET', environment },
+  });
+
 /** An interface-complete driver whose remote half is not bound yet. Always carries a fix. */
 export const storageNotImplemented = (feature: string, fix: string): StorageError =>
   new StorageError({

package/src/grant.ts

@@ -0,0 +1,100 @@
+// Single responsibility: minting ONE presigned PUT for ONE file, with the tenant prefix and the
+// policy already inside the signature. The client never names the key — it asks for a grant and
+// is told one — so a caller cannot aim an upload at another org's prefix, at an attached row it
+// does not own, or at a size the policy never allowed. Everything this returns is derived; the
+// only client input that survives is the filename's extension, and only if it survives a regex.
+
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import type { AttachmentTarget } from './attachment';
+import { attachmentKey, pendingKey, quarantineKey, uploadName } from './attachment';
+import type { StorageDriver } from './driver';
+import { contentTypeNotAllowed, tooLarge } from './errors';
+import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
+import type { UploadPolicy } from './upload';
+import { normalizeContentType, uploadPolicy } from './upload';
+
+export interface UploadRequest {
+  /** The client's own name for the file. Used for its extension and nothing else. */
+  readonly filename: string;
+  readonly contentType: string;
+  /**
+   * Optional, and never trusted: it only buys the client an early refusal. The bytes are counted
+   * again by `acceptSignedUpload`, which is the authority, so a lie here changes nothing.
+   */
+  readonly size?: number | undefined;
+}
+
+export interface UploadGrant {
+  /** Where the bytes will live. The app stores this on the row, never the URL. */
+  readonly key: string;
+  readonly url: string;
+  readonly method: 'PUT';
+  /** Normalised. The client MUST send exactly this as `Content-Type` or the accept refuses. */
+  readonly contentType: string;
+  readonly maxBytes: number;
+  /** Epoch ms. The grant's own view of the window; the signature is what actually enforces it. */
+  readonly expiresAt: number;
+}
+
+export interface GrantUploadInput {
+  readonly disk: StorageDriver;
+  /** The ACTOR's org, resolved server-side. A value read off the request is a tenant bypass. */
+  readonly orgId: string;
+  readonly request: UploadRequest;
+  readonly policy?: UploadPolicy | undefined;
+  /** Absent means the row does not exist yet, so the key lands under `pending/`. */
+  readonly target?: AttachmentTarget | undefined;
+  /**
+   * Land the bytes under `pending/quarantine/` instead, so nothing can promote them until the
+   * app's scan job calls `releaseQuarantine`. Only meaningful without a `target`: an upload
+   * aimed straight at a row has no promotion step left to gate.
+   */
+  readonly quarantine?: boolean | undefined;
+  readonly expiresInMs?: number | undefined;
+  readonly clock?: Clock | undefined;
+  /** Determinism seam for tests. Defaults to `crypto.randomUUID()`. */
+  readonly uploadId?: (() => string) | undefined;
+}
+
+/**
+ * Refuses before it signs. A URL only exists for a request the policy already accepted, so an
+ * over-limit or disallowed upload costs one round trip instead of a full transfer — and the
+ * signature then carries the same two constraints, so the client cannot widen either of them.
+ */
+export async function grantUpload(input: GrantUploadInput): Promise<UploadGrant> {
+  const policy = input.policy ?? uploadPolicy();
+  const clock = input.clock ?? systemClock;
+  const declared = normalizeContentType(input.request.contentType);
+  const name = uploadName(
+    (input.uploadId ?? (() => crypto.randomUUID()))(),
+    input.request.filename,
+  );
+  const pending =
+    input.quarantine === true ? quarantineKey(input.orgId, name) : pendingKey(input.orgId, name);
+  const key = input.target === undefined ? pending : attachmentKey(input.orgId, input.target, name);
+
+  if (!policy.allowedContentTypes.includes(declared)) {
+    throw contentTypeNotAllowed(key, declared, policy.allowedContentTypes);
+  }
+  const size = input.request.size;
+  if (size !== undefined && Number.isSafeInteger(size) && size > policy.maxBytes) {
+    throw tooLarge(key, size, policy.maxBytes);
+  }
+
+  const expiresInMs = input.expiresInMs ?? DEFAULT_SIGNED_URL_TTL_MS;
+  const url = await input.disk.signedUrl(key, {
+    method: 'PUT',
+    maxBytes: policy.maxBytes,
+    contentType: declared,
+    expiresInMs,
+  });
+  return {
+    key,
+    url,
+    method: 'PUT',
+    contentType: declared,
+    maxBytes: policy.maxBytes,
+    expiresAt: clock.now().getTime() + expiresInMs,
+  };
+}

package/src/index.ts

@@ -1,14 +1,44 @@
 // Single responsibility: the public API of @ultimat3/storage. Explicit named exports only —
 // every consumer imports from here, so this list is the package's contract.
 
+export type { AcceptSignedUploadInput, SignedRequestInput } from './accept';
+export { acceptSignedUpload, readSignedObject } from './accept';
 export type {
+  AttachmentTarget,
+  PromoteAttachmentInput,
+  ReleaseQuarantineInput,
+  SweepFailure,
+  SweepOrphansInput,
+  SweepResult,
+} from './attachment';
+export {
+  attachmentKey,
+  attachmentPrefix,
+  isPendingKey,
+  isQuarantinedKey,
+  PENDING_SEGMENT,
+  pendingKey,
+  pendingPrefix,
+  promoteAttachment,
+  QUARANTINE_SEGMENT,
+  quarantineKey,
+  quarantinePrefix,
+  releaseQuarantine,
+  sweepOrphans,
+  uploadExtension,
+  uploadName,
+} from './attachment';
+export type {
+  ByteLimit,
   ListOptions,
   ListPage,
   PutOptions,
+  ServerSideEncryption,
   SignedUrlMethod,
   SignedUrlOptions,
   StorageBody,
   StorageDriver,
+  StorageListEntry,
   StorageObject,
   StorageRead,
 } from './driver';
@@ -20,7 +50,12 @@ export {
   toBytes,
 } from './driver';
 export type { LocalDriverOptions } from './driver-local';
-export { localDriver } from './driver-local';
+export {
+  DEV_SIGNING_SECRET,
+  localDriver,
+  STORAGE_SIGNING_SECRET_KEY,
+  usesDevStorageSecret,
+} from './driver-local';
 export type {
   S3ClientLike,
   S3DriverOptions,
@@ -35,16 +70,27 @@ export {
   checksumMismatch,
   contentTypeMismatch,
   contentTypeNotAllowed,
+  deleteFailed,
   diskUnknown,
   isStorageError,
+  listFailed,
   objectNotFound,
+  orgMismatch,
   pathUnsafe,
+  putTooLarge,
+  quarantined,
   STORAGE_ERROR_CODES,
   STORAGE_ERROR_TITLES,
   StorageError,
+  signedUrlExpired,
+  signedUrlRejected,
+  signingSecretMissing,
   storageNotImplemented,
   tooLarge,
+  uploadFailed,
 } from './errors';
+export type { GrantUploadInput, UploadGrant, UploadRequest } from './grant';
+export { grantUpload } from './grant';
 export type {
   ImageFit,
   ImageFormat,
@@ -68,11 +114,13 @@ export {
 export {
   assertSafeKey,
   isSafeKey,
+  isTenantScoped,
   isWithinOrg,
   joinKey,
   keyDirname,
   keyExtname,
   MAX_KEY_LENGTH,
+  META_DIR,
   ORG_PREFIX,
   orgPrefix,
   scopedKey,
@@ -109,3 +157,17 @@ export {
   uploadPolicy,
   validateUpload,
 } from './upload';
+export type {
+  SignedPut,
+  SignedPutInput,
+  UploadedFile,
+  UploadFileInput,
+  UploadProgress,
+  UploadSource,
+} from './upload-client';
+export {
+  defaultSignedPut,
+  fetchSignedPut,
+  uploadFile,
+  xhrSignedPut,
+} from './upload-client';

package/src/path.ts

@@ -9,6 +9,15 @@ import { pathUnsafe } from './errors';
 export const MAX_KEY_LENGTH = 1024;
 export const ORG_PREFIX = 'org';
 
+/**
+ * Reserved first segment: the local driver's sidecar namespace, where an object's recorded
+ * content type and etag live. Without the reservation `<root>/.meta/a/b.json` was a legal object
+ * key, so an uploader could overwrite the sidecar for `a/b` and make a route serving that object
+ * answer `text/html` from the app's own origin. Reserved for EVERY driver, not just the local
+ * one — a key that is valid on S3 and refused on disk is two key rules.
+ */
+export const META_DIR = '.meta';
+
 // `%2e%2e%2f` decodes to `../` in any layer that decodes twice (proxy, then framework).
 const ENCODED_SEPARATOR = /%(?:2e|2f|5c|00)/i;
 
@@ -30,7 +39,9 @@ function unsafeReason(key: string): string | undefined {
   if (key.includes('\\')) return 'contains a backslash';
   if (key.startsWith('/')) return 'is absolute (leading "/")';
   if (ENCODED_SEPARATOR.test(key)) return 'contains a percent-encoded separator (%2e/%2f/%5c)';
-  for (const segment of key.split('/')) {
+  const segments = key.split('/');
+  if (segments[0] === META_DIR) return `starts with the reserved "${META_DIR}" segment`;
+  for (const segment of segments) {
     if (segment.length === 0) return 'contains an empty segment ("//" or a trailing "/")';
     if (segment === '.' || segment === '..') return `contains a "${segment}" segment`;
     if (segment !== segment.trim()) return `has a padded segment ${JSON.stringify(segment)}`;
@@ -85,6 +96,17 @@ export function isWithinOrg(key: string, orgId: string): boolean {
   return isSafeKey(key) && key.startsWith(orgPrefix(orgId));
 }
 
+/**
+ * Whether the key lives in the tenant namespace at all — `scopedKey` and `grantUpload` build
+ * `org/<id>/…`, `disk().put('logo.png', …)` does not. A surface serving objects has to tell the
+ * two apart: `isWithinOrg` alone would answer `false` for every un-scoped key and make an app's
+ * own shared assets unreachable, and dropping the check would make one tenant's prefix readable
+ * by another. The pair is the question "does this key belong to somebody else?".
+ */
+export function isTenantScoped(key: string): boolean {
+  return key.startsWith(`${ORG_PREFIX}/`);
+}
+
 /** `org/o1/a/b.png` -> `org/o1/a`. Empty for a top-level key. */
 export function keyDirname(key: string): string {
   const cut = key.lastIndexOf('/');

package/src/signed-url.ts

@@ -4,10 +4,14 @@
 // 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, systemClock } from '@ultimat3/core';
+import { type Clock, systemClock, timingSafeEqual } from '@ultimat3/core';
 import type { SignedUrlMethod } from './driver';
 import { assertSafeKey, isSafeKey } from './path';
 
+/** Re-exported so every existing `from '@ultimat3/storage'` import keeps working — the
+ * implementation now lives in `@ultimat3/core`, shared with `@ultimat3/auth`. */
+export { timingSafeEqual };
+
 export const SIGNED_URL_VERSION = 'v1';
 export const DEFAULT_SIGNED_URL_TTL_MS = 900_000;
 /** The dev server mounts the download/upload route here; S3 disks never use it. */
@@ -84,16 +88,6 @@ export async function signConstraints(
   return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
 }
 
-/** Length is public (fixed-width hex); the byte comparison must not early-exit. */
-export function timingSafeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let index = 0; index < a.length; index += 1) {
-    diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
-  }
-  return diff === 0;
-}
-
 const trimBase = (base: string): string => base.replace(/\/+$/, '');
 const encodeKey = (key: string): string => key.split('/').map(encodeURIComponent).join('/');
 
@@ -105,7 +99,11 @@ export async function buildSignedUrl(input: SignedUrlInput): Promise<string> {
     method: input.method ?? 'GET',
     expiresAt: clock.now().getTime() + (input.expiresInMs ?? DEFAULT_SIGNED_URL_TTL_MS),
     maxBytes: input.maxBytes,
-    contentType: input.contentType,
+    // An empty string is not a content type, and `canonicalRequest` renders it and `undefined`
+    // identically — so minting one would produce a URL indistinguishable from an unconstrained
+    // 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,
   };
   const params = new URLSearchParams();
   params.set(SIGNED_URL_PARAMS.method, constraints.method);
@@ -135,13 +133,29 @@ const fail = (reason: SignedUrlFailure, detail: string): SignedUrlVerification =
   detail,
 });
 
+/**
+ * `undefined` instead of the bare `URIError` `decodeURIComponent('%ZZ')` throws. The URL is
+ * attacker-supplied and the header's promise is that verification never throws — an exception
+ * here would escape as an uncoded 500 for a caller whose URL is simply malformed. Nothing is
+ * loosened: `buildSignedUrl` percent-encodes every segment, so a segment that will not decode
+ * was never minted by this package.
+ */
+const decodeSegment = (segment: string): string | undefined => {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return undefined;
+  }
+};
+
 function parseConstraints(url: URL, base: string): SignedUrlConstraints | SignedUrlFailure {
   if (!url.pathname.startsWith(`${base}/`)) return 'malformed';
-  const key = url.pathname
+  const segments = url.pathname
     .slice(base.length + 1)
     .split('/')
-    .map(decodeURIComponent)
-    .join('/');
+    .map(decodeSegment);
+  if (segments.includes(undefined)) return 'malformed';
+  const key = segments.join('/');
   if (!isSafeKey(key)) return 'unsafe-key';
   const method = url.searchParams.get(SIGNED_URL_PARAMS.method) ?? 'GET';
   if (method !== 'GET' && method !== 'PUT') return 'malformed';
@@ -152,12 +166,16 @@ function parseConstraints(url: URL, base: string): SignedUrlConstraints | Signed
   if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes < 0)) {
     return 'malformed';
   }
+  const rawContentType = url.searchParams.get(SIGNED_URL_PARAMS.contentType);
+  // 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';
   return {
     key,
     method,
     expiresAt,
     maxBytes,
-    contentType: url.searchParams.get(SIGNED_URL_PARAMS.contentType) ?? undefined,
+    contentType: rawContentType ?? undefined,
   };
 }