@edge-base/server 0.2.9 → 0.3.1

package/src/routes/storage.ts

@@ -305,8 +305,34 @@ function checkServiceKey(env: Env, header: string | undefined, scope: string, re
 type SignedTokenClaims = {
   expiresAt: number;
   maxBytes: number | null;
+  file?: SignedTokenFileMetadata | null;
 };
 
+type SignedTokenFileMetadata = {
+  size: number;
+  contentType?: string;
+  etag?: string;
+  uploadedAt?: string;
+  uploadedBy?: string | null;
+  customMetadata?: Record<string, string>;
+};
+
+type SignedTokenOptions = {
+  maxBytes?: number | null;
+  file?: SignedTokenFileMetadata | null;
+};
+
+type TrackedMultipartPart = {
+  partNumber: number;
+  etag: string;
+  size?: number;
+};
+
+type ParsedDownloadRange =
+  | { kind: 'full' }
+  | { kind: 'partial'; offset: number; end: number; length: number }
+  | { kind: 'unsatisfiable' };
+
 function parseByteSize(value?: string): number | null {
   if (!value) return null;
   const trimmed = value.trim();
@@ -328,18 +354,98 @@ function parseByteSize(value?: string): number | null {
   return amount * multiplier;
 }
 
+function emptySignedTokenClaims(expiresAt = 0, maxBytes: number | null = null): SignedTokenClaims {
+  return { expiresAt, maxBytes, file: null };
+}
+
+function normalizeSignedTokenOptions(options?: number | null | SignedTokenOptions): Required<Pick<SignedTokenOptions, 'maxBytes'>> & Pick<SignedTokenOptions, 'file'> {
+  const rawMaxBytes = typeof options === 'object' && options !== null
+    ? options.maxBytes
+    : options;
+  const maxBytes = typeof rawMaxBytes === 'number' && Number.isFinite(rawMaxBytes)
+    ? Math.max(0, Math.trunc(rawMaxBytes))
+    : null;
+  const file = typeof options === 'object' && options !== null
+    ? normalizeSignedFileMetadata(options.file)
+    : null;
+  return { maxBytes, file };
+}
+
+function normalizeSignedFileMetadata(file?: SignedTokenFileMetadata | null): SignedTokenFileMetadata | null {
+  if (!file || typeof file.size !== 'number' || !Number.isFinite(file.size) || file.size < 0) {
+    return null;
+  }
+
+  const customMetadata: Record<string, string> = {};
+  if (file.customMetadata && typeof file.customMetadata === 'object') {
+    for (const [key, value] of Object.entries(file.customMetadata)) {
+      if (typeof value === 'string') customMetadata[key] = value;
+    }
+  }
+
+  const normalized: SignedTokenFileMetadata = {
+    size: Math.trunc(file.size),
+  };
+  if (typeof file.contentType === 'string' && file.contentType) normalized.contentType = file.contentType;
+  if (typeof file.etag === 'string' && file.etag) normalized.etag = file.etag;
+  if (typeof file.uploadedAt === 'string' && file.uploadedAt) normalized.uploadedAt = file.uploadedAt;
+  if (typeof file.uploadedBy === 'string' || file.uploadedBy === null) normalized.uploadedBy = file.uploadedBy;
+  if (Object.keys(customMetadata).length > 0) normalized.customMetadata = customMetadata;
+  return normalized;
+}
+
+function encodeBase64Url(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+function decodeBase64Url(value: string): string {
+  const padded = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - value.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return new TextDecoder().decode(bytes);
+}
+
+function signedFileMetadataFromObject(obj: R2Object): SignedTokenFileMetadata {
+  return {
+    size: obj.size,
+    contentType: obj.httpMetadata?.contentType || 'application/octet-stream',
+    etag: obj.etag,
+    uploadedAt: obj.uploaded?.toISOString(),
+  };
+}
+
 /** Create HMAC-based signed URL token. */
 export async function createSignedToken(
   key: string,
   bucket: string,
   expiresAt: number,
   secret: string,
-  maxBytes?: number | null,
+  options?: number | null | SignedTokenOptions,
 ): Promise<string> {
   const encoder = new TextEncoder();
-  const normalizedMaxBytes = typeof maxBytes === 'number' && Number.isFinite(maxBytes)
-    ? Math.max(0, Math.trunc(maxBytes))
-    : null;
+  const { maxBytes: normalizedMaxBytes, file } = normalizeSignedTokenOptions(options);
+  if (file) {
+    const payload = encodeBase64Url(JSON.stringify({
+      v: 2,
+      bucket,
+      key,
+      exp: Math.trunc(expiresAt),
+      max: normalizedMaxBytes,
+      file,
+    }));
+    const data = `v2.${payload}`;
+    const cryptoKey = await crypto.subtle.importKey(
+      'raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
+    );
+    const signature = await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(data));
+    const sigHex = Array.from(new Uint8Array(signature)).map(b => b.toString(16).padStart(2, '0')).join('');
+    return `${data}.${sigHex}`;
+  }
+
   const data = `${bucket}:${key}:${expiresAt}:${normalizedMaxBytes ?? ''}`;
   const cryptoKey = await crypto.subtle.importKey(
     'raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
@@ -359,18 +465,63 @@ async function verifySignedToken(
   secret: string,
 ): Promise<{ valid: boolean; claims: SignedTokenClaims }> {
   const parts = token.split('.');
+  if (parts.length === 3 && parts[0] === 'v2') {
+    const payload = parts[1]!;
+    const signature = parts[2]!;
+    let claims: SignedTokenClaims = emptySignedTokenClaims();
+    try {
+      const parsed = JSON.parse(decodeBase64Url(payload)) as {
+        v?: unknown;
+        bucket?: unknown;
+        key?: unknown;
+        exp?: unknown;
+        max?: unknown;
+        file?: unknown;
+      };
+      const expiresAt = typeof parsed.exp === 'number' ? Math.trunc(parsed.exp) : NaN;
+      const maxBytes = typeof parsed.max === 'number' && Number.isFinite(parsed.max)
+        ? Math.max(0, Math.trunc(parsed.max))
+        : null;
+      const file = normalizeSignedFileMetadata(parsed.file as SignedTokenFileMetadata | null | undefined);
+      claims = { expiresAt, maxBytes, file };
+      if (
+        parsed.v !== 2
+        || parsed.bucket !== bucket
+        || parsed.key !== key
+        || !Number.isFinite(expiresAt)
+        || Date.now() > expiresAt
+      ) {
+        return { valid: false, claims };
+      }
+    } catch {
+      return { valid: false, claims: emptySignedTokenClaims() };
+    }
+
+    const encoder = new TextEncoder();
+    const data = `v2.${payload}`;
+    const cryptoKey = await crypto.subtle.importKey(
+      'raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
+    );
+    const expected = await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(data));
+    const expectedHex = Array.from(new Uint8Array(expected)).map(b => b.toString(16).padStart(2, '0')).join('');
+    return {
+      valid: timingSafeEqual(signature, expectedHex),
+      claims,
+    };
+  }
+
   if (parts.length !== 2 && parts.length !== 3) {
-    return { valid: false, claims: { expiresAt: 0, maxBytes: null } };
+    return { valid: false, claims: emptySignedTokenClaims() };
   }
   const expiresAt = parseInt(parts[0]!, 10);
   const maxBytes = parts.length === 3 ? parseInt(parts[1]!, 10) : null;
   const signature = parts[parts.length - 1]!;
 
   if (isNaN(expiresAt) || Date.now() > expiresAt) {
-    return { valid: false, claims: { expiresAt, maxBytes: Number.isFinite(maxBytes ?? NaN) ? maxBytes : null } };
+    return { valid: false, claims: emptySignedTokenClaims(expiresAt, Number.isFinite(maxBytes ?? NaN) ? maxBytes : null) };
   }
   if (parts.length === 3 && !Number.isFinite(maxBytes)) {
-    return { valid: false, claims: { expiresAt, maxBytes: null } };
+    return { valid: false, claims: emptySignedTokenClaims(expiresAt) };
   }
 
   const encoder = new TextEncoder();
@@ -385,10 +536,66 @@ async function verifySignedToken(
     claims: {
       expiresAt,
       maxBytes: parts.length === 3 ? maxBytes : null,
+      file: null,
     },
   };
 }
 
+async function verifySignedUploadQuery(
+  c: Context<HonoEnv>,
+  bucketName: string,
+  key: string,
+): Promise<SignedTokenClaims | null> {
+  const token = c.req.query('token');
+  const tokenKey = c.req.query('key');
+  if (!token) return null;
+  if (tokenKey && tokenKey !== key) {
+    throw new EdgeBaseError(400, 'Signed upload key mismatch.', undefined, 'validation-failed');
+  }
+  const secret = c.env.JWT_USER_SECRET;
+  if (!secret) {
+    throw new EdgeBaseError(403, 'Signed upload tokens require JWT_USER_SECRET to be configured.', undefined, 'access-denied');
+  }
+  const verified = await verifySignedToken(token, key, bucketName, secret);
+  if (!verified.valid) {
+    throw new EdgeBaseError(403, 'Signed upload token is invalid or expired.', undefined, 'access-denied');
+  }
+  return verified.claims;
+}
+
+function requestContentLength(c: Context<HonoEnv>): number | null {
+  const header = c.req.header('content-length');
+  if (!header) return null;
+  const size = Number(header);
+  return Number.isFinite(size) && size >= 0 ? Math.floor(size) : null;
+}
+
+async function assertSignedMultipartSizeWithinLimit(
+  c: Context<HonoEnv>,
+  bucketName: string,
+  key: string,
+  uploadId: string,
+  parts: Array<{ partNumber: number; etag: string }>,
+  maxBytes: number,
+) {
+  const kvKey = partTrackingKey(bucketName, key, uploadId);
+  const existing = await c.env.KV.get(kvKey, 'json') as TrackedMultipartPart[] | null;
+  const tracked = new Map(
+    (existing ?? []).map((part) => [`${part.partNumber}:${part.etag}`, part] as const),
+  );
+  let total = 0;
+  for (const part of parts) {
+    const trackedPart = tracked.get(`${part.partNumber}:${part.etag}`);
+    if (!trackedPart || typeof trackedPart.size !== 'number' || !Number.isFinite(trackedPart.size)) {
+      throw new EdgeBaseError(400, 'Signed multipart upload is missing tracked part size metadata.', undefined, 'validation-failed');
+    }
+    total += trackedPart.size;
+    if (total > maxBytes) {
+      throw new EdgeBaseError(413, `Signed upload exceeds maxFileSize of ${maxBytes} bytes.`, undefined, 'payload-too-large');
+    }
+  }
+}
+
 /** Parse duration string (e.g. '1h', '30m') to milliseconds. Max 7 days. */
 export function parseDuration(str: string): number {
   const match = str.match(/^(\d+)(s|m|h|d)$/);
@@ -447,6 +654,85 @@ function buildMetadata(obj: R2Object): R2FileMeta {
   } as R2FileMeta;
 }
 
+function buildMetadataFromSignedFile(key: string, file: SignedTokenFileMetadata): R2FileMeta {
+  return {
+    key,
+    size: file.size,
+    contentType: file.contentType || 'application/octet-stream',
+    etag: file.etag || '',
+    uploadedAt: file.uploadedAt,
+    uploadedBy: file.uploadedBy ?? file.customMetadata?.uploadedBy ?? null,
+    customMetadata: file.customMetadata || {},
+  } as R2FileMeta;
+}
+
+function hasBlockingBeforeDownloadHooks(env: Env, bucketName: string): boolean {
+  const pluginHooks = getFunctionsByTrigger('storage', { type: 'storage', event: 'beforeDownload' } as unknown as StorageTrigger);
+  if (pluginHooks.length > 0) return true;
+  return !!getStorageHooks(env, bucketName)?.beforeDownload;
+}
+
+function parseDownloadRange(header: string | undefined, size: number): ParsedDownloadRange {
+  if (!header) return { kind: 'full' };
+  const match = header.trim().match(/^bytes=(.+)$/i);
+  if (!match) return { kind: 'full' };
+  const range = match[1]?.trim() ?? '';
+  if (!range || range.includes(',')) return { kind: 'unsatisfiable' };
+
+  const [rawStart, rawEnd] = range.split('-', 2);
+  if (rawStart === undefined || rawEnd === undefined) return { kind: 'unsatisfiable' };
+
+  let offset: number;
+  let end: number;
+
+  if (rawStart === '') {
+    const suffixLength = Number(rawEnd);
+    if (!Number.isSafeInteger(suffixLength) || suffixLength <= 0 || size <= 0) {
+      return { kind: 'unsatisfiable' };
+    }
+    offset = Math.max(size - suffixLength, 0);
+    end = size - 1;
+  } else {
+    const start = Number(rawStart);
+    const requestedEnd = rawEnd === '' ? size - 1 : Number(rawEnd);
+    if (
+      !Number.isSafeInteger(start)
+      || !Number.isSafeInteger(requestedEnd)
+      || start < 0
+      || requestedEnd < start
+      || start >= size
+    ) {
+      return { kind: 'unsatisfiable' };
+    }
+    offset = start;
+    end = Math.min(requestedEnd, size - 1);
+  }
+
+  return { kind: 'partial', offset, end, length: end - offset + 1 };
+}
+
+function createDownloadHeaders(meta: R2FileMeta, signedClaims?: SignedTokenClaims | null): Headers {
+  const headers = new Headers();
+  headers.set('Content-Type', meta.contentType || 'application/octet-stream');
+  if (meta.etag) {
+    headers.set('ETag', meta.etag);
+  }
+  headers.set('Accept-Ranges', 'bytes');
+  if (meta.uploadedAt) {
+    const uploadedAt = new Date(meta.uploadedAt);
+    if (!Number.isNaN(uploadedAt.getTime())) {
+      headers.set('Last-Modified', uploadedAt.toUTCString());
+    }
+  }
+  if (signedClaims) {
+    const maxAge = Math.max(0, Math.floor((signedClaims.expiresAt - Date.now()) / 1000));
+    if (maxAge > 0) {
+      headers.set('Cache-Control', `private, max-age=${Math.min(maxAge, 3600)}`);
+    }
+  }
+  return headers;
+}
+
 const STORAGE_OFFSET_CURSOR_PREFIX = 'offset:';
 
 function parseStorageListInteger(raw: string | undefined, name: string, fallback: number): number {
@@ -616,12 +902,17 @@ const uploadFile = createRoute({
   summary: 'Upload file',
   request: {
     params: z.object({ bucket: z.string() }),
+    query: z.object({
+      key: z.string().optional().openapi({ description: 'Optional signed upload key echoed from a signed upload URL.' }),
+      token: z.string().optional().openapi({ description: 'Optional signed upload token for write-rule-bypassing upload grants.' }),
+    }),
     body: { content: { 'multipart/form-data': { schema: z.object({}).passthrough() } }, required: true },
   },
   responses: {
     201: { description: 'File uploaded', content: { 'application/json': { schema: jsonResponseSchema } } },
     400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
     403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
+    413: { description: 'Payload too large', content: { 'application/json': { schema: errorResponseSchema } } },
   },
 });
 
@@ -908,7 +1199,10 @@ const getUploadParts = createRoute({
   summary: 'Get uploaded parts',
   request: {
     params: z.object({ bucket: z.string(), uploadId: z.string() }),
-    query: z.object({ key: z.string() }),
+    query: z.object({
+      key: z.string(),
+      token: z.string().optional().openapi({ description: 'Optional signed upload token for write-rule-bypassing upload grants.' }),
+    }),
   },
   responses: {
     200: { description: 'Success', content: { 'application/json': { schema: jsonResponseSchema } } },
@@ -928,14 +1222,17 @@ storage.openapi(getUploadParts, async (c) => {
   }
 
   // Security: check write rule (resume upload = write operation)
-  const serviceKeyBypass = checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
-  if (!serviceKeyBypass) {
+  const signedClaims = await verifySignedUploadQuery(c, bucketName, key);
+  const serviceKeyBypass = signedClaims
+    ? false
+    : checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
+  if (!signedClaims && !serviceKeyBypass) {
     const auth = c.get('auth') as AuthContext | null;
     checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
   }
 
   const kvKey = partTrackingKey(bucketName, key, uploadId);
-  const parts = await c.env.KV.get(kvKey, 'json') as Array<{ partNumber: number; etag: string }> | null;
+  const parts = await c.env.KV.get(kvKey, 'json') as TrackedMultipartPart[] | null;
 
   return c.json({
     uploadId,
@@ -955,8 +1252,10 @@ const downloadFile = createRoute({
   },
   responses: {
     200: { description: 'File content' },
+    206: { description: 'Partial file content' },
     403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
     404: { description: 'Not found', content: { 'application/json': { schema: errorResponseSchema } } },
+    416: { description: 'Range not satisfiable' },
   },
 });
 
@@ -968,6 +1267,7 @@ const handleDownloadFile = async (c: Context<HonoEnv>) => {
   // Check for signed URL token
   const token = c.req.query('token');
   let skipRules = false;
+  let signedClaims: SignedTokenClaims | null = null;
 
   if (token) {
     // Asymmetric fail-closed (#99): secret 미설정 시 토큰 무시 → 보안 규칙으로 fallback
@@ -976,14 +1276,31 @@ const handleDownloadFile = async (c: Context<HonoEnv>) => {
       const verified = await verifySignedToken(token, key, bucketName, secret);
       if (verified.valid) {
         skipRules = true;
+        signedClaims = verified.claims;
       }
     }
   }
 
   const fullKey = r2Key(bucketName, key);
-  const obj = await c.env.STORAGE.get(fullKey);
-  if (!obj) {
-    throw new EdgeBaseError(404, 'File not found.', undefined, 'not-found');
+  const rangeHeader = c.req.header('Range') ?? c.req.header('range');
+  const isByteRangeRequest = !!rangeHeader && /^bytes=/i.test(rangeHeader.trim());
+  const signedMetadataAllowed = skipRules && isByteRangeRequest && !!signedClaims?.file && !hasBlockingBeforeDownloadHooks(c.env, bucketName);
+  let fileMeta: R2FileMeta | null = signedMetadataAllowed && signedClaims?.file
+    ? buildMetadataFromSignedFile(key, signedClaims.file)
+    : null;
+  let bodyObj: R2ObjectBody | null = null;
+
+  if (!fileMeta) {
+    const file = rangeHeader
+      ? await c.env.STORAGE.head(fullKey)
+      : await c.env.STORAGE.get(fullKey);
+    if (!file) {
+      throw new EdgeBaseError(404, 'File not found.', undefined, 'not-found');
+    }
+    fileMeta = buildMetadata(file);
+    if (!rangeHeader) {
+      bodyObj = file as R2ObjectBody;
+    }
   }
 
   // Security: check read rule
@@ -991,41 +1308,57 @@ const handleDownloadFile = async (c: Context<HonoEnv>) => {
     const serviceKeyBypass = checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:read`, c.req);
     if (!serviceKeyBypass) {
       const auth = c.get('auth') as AuthContext | null;
-      const resource = buildMetadata(obj);
-      checkStorageRule(bucketConfig.access?.read, auth, resource, 'read', bucketName, release);
+      checkStorageRule(bucketConfig.access?.read, auth, fileMeta, 'read', bucketName, release);
     }
   }
 
   // Plugin blocking storage hooks (beforeDownload)
   {
     const dlAuth = c.get('auth') as AuthContext | null;
-    const dlMeta = buildMetadata(obj);
-    await executeBlockingStorageHooks('beforeDownload', { ...dlMeta, bucket: bucketName }, dlAuth, c.env, getWorkerUrl(c.req.url, c.env));
+    await executeBlockingStorageHooks('beforeDownload', { ...fileMeta, bucket: bucketName }, dlAuth, c.env, getWorkerUrl(c.req.url, c.env));
   }
 
   // beforeDownload hook — blocking, throw to reject
   const hooks = getStorageHooks(c.env, bucketName);
   if (hooks?.beforeDownload) {
     const auth = c.get('auth') as AuthContext | null;
-    const meta = buildMetadata(obj);
     const hookCtx = buildStorageHookCtx(c.env, c.executionCtx, getWorkerUrl(c.req.url, c.env));
     try {
-      await hooks.beforeDownload(auth, meta, hookCtx);
+      await hooks.beforeDownload(auth, fileMeta, hookCtx);
     } catch (error) {
       throw normalizeStorageHookError(error, 'beforeDownload');
     }
   }
 
-  // Stream response
-  const headers = new Headers();
-  headers.set('Content-Type', obj.httpMetadata?.contentType || 'application/octet-stream');
-  headers.set('Content-Length', String(obj.size));
-  headers.set('ETag', obj.etag);
-  if (obj.uploaded) {
-    headers.set('Last-Modified', obj.uploaded.toUTCString());
+  const parsedRange = parseDownloadRange(rangeHeader, fileMeta.size);
+  const headers = createDownloadHeaders(fileMeta, skipRules ? signedClaims : null);
+
+  if (parsedRange.kind === 'unsatisfiable') {
+    headers.set('Content-Range', `bytes */${fileMeta.size}`);
+    headers.set('Content-Length', '0');
+    return new Response(null, { status: 416, headers });
+  }
+
+  if (parsedRange.kind === 'partial') {
+    const rangedObj = await c.env.STORAGE.get(fullKey, {
+      range: { offset: parsedRange.offset, length: parsedRange.length },
+    });
+    if (!rangedObj) {
+      throw new EdgeBaseError(404, 'File not found.', undefined, 'not-found');
+    }
+    headers.set('Content-Length', String(parsedRange.length));
+    headers.set('Content-Range', `bytes ${parsedRange.offset}-${parsedRange.end}/${fileMeta.size}`);
+    return new Response(rangedObj.body, { status: 206, headers });
   }
 
-  return new Response(obj.body, { headers });
+  if (!bodyObj) {
+    bodyObj = await c.env.STORAGE.get(fullKey);
+    if (!bodyObj) {
+      throw new EdgeBaseError(404, 'File not found.', undefined, 'not-found');
+    }
+  }
+  headers.set('Content-Length', String(fileMeta.size));
+  return new Response(bodyObj.body, { headers });
 };
 storage.openapi(downloadFile, handleDownloadFile);
 
@@ -1298,7 +1631,9 @@ storage.openapi(createSignedDownloadUrl, async (c) => {
   if (!secret) {
     throw new EdgeBaseError(500, 'Signed URLs require JWT_USER_SECRET to be configured.', undefined, 'internal-error');
   }
-  const token = await createSignedToken(body.key, bucketName, expiresAt, secret);
+  const token = await createSignedToken(body.key, bucketName, expiresAt, secret, {
+    file: signedFileMetadataFromObject(obj),
+  });
 
   // Build signed URL
   const url = new URL(c.req.url);
@@ -1362,7 +1697,9 @@ storage.openapi(createSignedDownloadUrls, async (c) => {
     const obj = await c.env.STORAGE.head(fullKey);
     if (!obj) continue; // skip non-existent files
 
-    const token = await createSignedToken(key, bucketName, expiresAt, secret);
+    const token = await createSignedToken(key, bucketName, expiresAt, secret, {
+      file: signedFileMetadataFromObject(obj),
+    });
     urls.push({
       key,
       url: `${url.protocol}//${url.host}/api/storage/${encodeURIComponent(bucketName)}/${encodeURIComponent(key)}?token=${token}`,
@@ -1445,6 +1782,10 @@ const createMultipartUpload = createRoute({
   summary: 'Start multipart upload',
   request: {
     params: z.object({ bucket: z.string() }),
+    query: z.object({
+      key: z.string().optional().openapi({ description: 'Optional signed upload key echoed from a signed upload URL.' }),
+      token: z.string().optional().openapi({ description: 'Optional signed upload token for write-rule-bypassing upload grants.' }),
+    }),
     body: { content: { 'application/json': { schema: z.object({ key: z.string(), contentType: z.string().optional(), customMetadata: z.record(z.string(), z.string()).optional() }) } }, required: true },
   },
   responses: {
@@ -1458,19 +1799,22 @@ storage.openapi(createMultipartUpload, async (c) => {
   const bucketName = c.req.param('bucket')!;
   const { bucketConfig, release } = getBucketConfig(c.env, bucketName);
 
-  // Security: check write rule
-  const serviceKeyBypass = checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
-  if (!serviceKeyBypass) {
-    const auth = c.get('auth') as AuthContext | null;
-    checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
-  }
-
   const body = await c.req.json<{ key: string; contentType?: string; customMetadata?: Record<string, string> }>();
   if (!body.key) {
     throw new EdgeBaseError(400, 'Missing required field: key.', undefined, 'validation-failed');
   }
   validateStorageKey(body.key);
 
+  // Security: check signed upload token or write rule
+  const signedClaims = await verifySignedUploadQuery(c, bucketName, body.key);
+  const serviceKeyBypass = signedClaims
+    ? false
+    : checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
+  if (!signedClaims && !serviceKeyBypass) {
+    const auth = c.get('auth') as AuthContext | null;
+    checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
+  }
+
   const auth = c.get('auth') as AuthContext | null;
   const customMetadata = body.customMetadata || {};
   if (auth?.id) {
@@ -1497,12 +1841,19 @@ const uploadPart = createRoute({
   summary: 'Upload a part',
   request: {
     params: z.object({ bucket: z.string() }),
-    body: { content: { 'application/json': { schema: z.record(z.string(), z.unknown()) } }, required: true },
+    query: z.object({
+      uploadId: z.string(),
+      partNumber: z.string(),
+      key: z.string(),
+      token: z.string().optional().openapi({ description: 'Optional signed upload token for write-rule-bypassing upload grants.' }),
+    }),
+    body: { content: { 'application/octet-stream': { schema: z.string().openapi({ format: 'binary' }) } }, required: true },
   },
   responses: {
     200: { description: 'Success', content: { 'application/json': { schema: jsonResponseSchema } } },
     400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
     403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
+    413: { description: 'Payload too large', content: { 'application/json': { schema: errorResponseSchema } } },
   },
 });
 
@@ -1510,13 +1861,6 @@ storage.openapi(uploadPart, async (c) => {
   const bucketName = c.req.param('bucket')!;
   const { bucketConfig, release } = getBucketConfig(c.env, bucketName);
 
-  // Security: check write rule
-  const serviceKeyBypass = checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
-  if (!serviceKeyBypass) {
-    const auth = c.get('auth') as AuthContext | null;
-    checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
-  }
-
   const uploadId = c.req.query('uploadId');
   const partNumber = parseInt(c.req.query('partNumber') || '0', 10);
   const key = c.req.query('key');
@@ -1524,6 +1868,24 @@ storage.openapi(uploadPart, async (c) => {
   if (!uploadId || !partNumber || !key) {
     throw new EdgeBaseError(400, 'Missing required query params: uploadId, partNumber, key.', undefined, 'validation-failed');
   }
+  validateStorageKey(key);
+
+  // Security: check signed upload token or write rule
+  const signedClaims = await verifySignedUploadQuery(c, bucketName, key);
+  const serviceKeyBypass = signedClaims
+    ? false
+    : checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
+  if (!signedClaims && !serviceKeyBypass) {
+    const auth = c.get('auth') as AuthContext | null;
+    checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
+  }
+  const partSize = requestContentLength(c);
+  if (signedClaims?.maxBytes != null && partSize == null) {
+    throw new EdgeBaseError(400, 'Signed multipart upload parts require Content-Length.', undefined, 'validation-failed');
+  }
+  if (signedClaims?.maxBytes != null && partSize !== null && partSize > signedClaims.maxBytes) {
+    throw new EdgeBaseError(413, `Signed upload exceeds maxFileSize of ${signedClaims.maxBytes} bytes.`, undefined, 'payload-too-large');
+  }
 
   const fullKey = r2Key(bucketName, key);
   const multipartUpload = c.env.STORAGE.resumeMultipartUpload(fullKey, uploadId);
@@ -1532,14 +1894,16 @@ storage.openapi(uploadPart, async (c) => {
 
   // M17: Save part info to KV for resume tracking
   const kvKey = partTrackingKey(bucketName, key, uploadId);
-  const existing = await c.env.KV.get(kvKey, 'json') as Array<{ partNumber: number; etag: string }> | null;
+  const existing = await c.env.KV.get(kvKey, 'json') as TrackedMultipartPart[] | null;
   const parts = existing || [];
   // Replace if same partNumber exists (re-upload), otherwise append
   const idx = parts.findIndex(p => p.partNumber === part.partNumber);
+  const trackedPart: TrackedMultipartPart = { partNumber: part.partNumber, etag: part.etag };
+  if (partSize !== null) trackedPart.size = partSize;
   if (idx >= 0) {
-    parts[idx] = { partNumber: part.partNumber, etag: part.etag };
+    parts[idx] = trackedPart;
   } else {
-    parts.push({ partNumber: part.partNumber, etag: part.etag });
+    parts.push(trackedPart);
   }
   await c.env.KV.put(kvKey, JSON.stringify(parts), { expirationTtl: PART_TRACKING_TTL });
 
@@ -1557,12 +1921,17 @@ const completeMultipartUpload = createRoute({
   summary: 'Complete multipart upload',
   request: {
     params: z.object({ bucket: z.string() }),
+    query: z.object({
+      key: z.string().optional().openapi({ description: 'Optional signed upload key echoed from a signed upload URL.' }),
+      token: z.string().optional().openapi({ description: 'Optional signed upload token for write-rule-bypassing upload grants.' }),
+    }),
     body: { content: { 'application/json': { schema: z.object({ uploadId: z.string(), key: z.string(), parts: z.array(z.object({ partNumber: z.number(), etag: z.string() })) }) } }, required: true },
   },
   responses: {
     200: { description: 'Success', content: { 'application/json': { schema: jsonResponseSchema } } },
     400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
     403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
+    413: { description: 'Payload too large', content: { 'application/json': { schema: errorResponseSchema } } },
   },
 });
 
@@ -1570,13 +1939,6 @@ storage.openapi(completeMultipartUpload, async (c) => {
   const bucketName = c.req.param('bucket')!;
   const { bucketConfig, release } = getBucketConfig(c.env, bucketName);
 
-  // Security: check write rule
-  const serviceKeyBypass = checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
-  if (!serviceKeyBypass) {
-    const auth = c.get('auth') as AuthContext | null;
-    checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
-  }
-
   const body = await c.req.json<{
     uploadId: string;
     key: string;
@@ -1586,6 +1948,20 @@ storage.openapi(completeMultipartUpload, async (c) => {
   if (!body.uploadId || !body.key || !body.parts?.length) {
     throw new EdgeBaseError(400, 'Missing required fields: uploadId, key, parts.', undefined, 'validation-failed');
   }
+  validateStorageKey(body.key);
+
+  // Security: check signed upload token or write rule
+  const signedClaims = await verifySignedUploadQuery(c, bucketName, body.key);
+  const serviceKeyBypass = signedClaims
+    ? false
+    : checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
+  if (!signedClaims && !serviceKeyBypass) {
+    const auth = c.get('auth') as AuthContext | null;
+    checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
+  }
+  if (signedClaims?.maxBytes != null) {
+    await assertSignedMultipartSizeWithinLimit(c, bucketName, body.key, body.uploadId, body.parts, signedClaims.maxBytes);
+  }
 
   const fullKey = r2Key(bucketName, body.key);
   const multipartUpload = c.env.STORAGE.resumeMultipartUpload(fullKey, body.uploadId);
@@ -1610,6 +1986,10 @@ const abortMultipartUpload = createRoute({
   summary: 'Abort multipart upload',
   request: {
     params: z.object({ bucket: z.string() }),
+    query: z.object({
+      key: z.string().optional().openapi({ description: 'Optional signed upload key echoed from a signed upload URL.' }),
+      token: z.string().optional().openapi({ description: 'Optional signed upload token for write-rule-bypassing upload grants.' }),
+    }),
     body: { content: { 'application/json': { schema: z.object({ uploadId: z.string(), key: z.string() }) } }, required: true },
   },
   responses: {
@@ -1623,17 +2003,21 @@ storage.openapi(abortMultipartUpload, async (c) => {
   const bucketName = c.req.param('bucket')!;
   const { bucketConfig, release } = getBucketConfig(c.env, bucketName);
 
-  // Security: check write rule
-  const serviceKeyBypass = checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
-  if (!serviceKeyBypass) {
-    const auth = c.get('auth') as AuthContext | null;
-    checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
-  }
-
   const body = await c.req.json<{ uploadId: string; key: string }>();
   if (!body.uploadId || !body.key) {
     throw new EdgeBaseError(400, 'Missing required fields: uploadId, key.', undefined, 'validation-failed');
   }
+  validateStorageKey(body.key);
+
+  // Security: check signed upload token or write rule
+  const signedClaims = await verifySignedUploadQuery(c, bucketName, body.key);
+  const serviceKeyBypass = signedClaims
+    ? false
+    : checkServiceKey(c.env, c.req.header('X-EdgeBase-Service-Key'), `storage:bucket:${bucketName}:write`, c.req);
+  if (!signedClaims && !serviceKeyBypass) {
+    const auth = c.get('auth') as AuthContext | null;
+    checkStorageRule(bucketConfig.access?.write, auth, null, 'write', bucketName, release);
+  }
 
   const fullKey = r2Key(bucketName, body.key);
   const multipartUpload = c.env.STORAGE.resumeMultipartUpload(fullKey, body.uploadId);