@se-studio/contentful-cms 3.0.3 → 3.1.1

package/dist/staged-upload/hmac.js

@@ -0,0 +1,43 @@
+import * as crypto from 'node:crypto';
+export function getUploadHmacSecret() {
+    const value = process.env['CMS_EDIT_UPLOAD_HMAC_SECRET']?.trim();
+    if (!value) {
+        throw new Error('Missing required environment variable: CMS_EDIT_UPLOAD_HMAC_SECRET');
+    }
+    return value;
+}
+export function buildUploadSignaturePayload(uploadId, userId, exp) {
+    return `${uploadId}:${userId}:${String(exp)}`;
+}
+export function signUploadUrl(uploadId, userId, exp, secret) {
+    const payload = buildUploadSignaturePayload(uploadId, userId, exp);
+    return crypto.createHmac('sha256', secret).update(payload).digest('hex');
+}
+export function verifyUploadSignature(uploadId, userId, exp, sig, secret) {
+    if (!sig || !uploadId || !userId) {
+        return false;
+    }
+    const expected = signUploadUrl(uploadId, userId, exp, secret);
+    try {
+        const expectedBuf = Buffer.from(expected, 'hex');
+        const actualBuf = Buffer.from(sig, 'hex');
+        if (expectedBuf.length !== actualBuf.length) {
+            return false;
+        }
+        return crypto.timingSafeEqual(expectedBuf, actualBuf);
+    }
+    catch {
+        return false;
+    }
+}
+export function buildStagedUploadUrl(origin, uploadId, userId, exp, secret) {
+    const sig = signUploadUrl(uploadId, userId, exp, secret);
+    const params = new URLSearchParams({
+        id: uploadId,
+        uid: userId,
+        exp: String(exp),
+        sig,
+    });
+    return `${origin.replace(/\/$/, '')}/api/staged-upload?${params.toString()}`;
+}
+//# sourceMappingURL=hmac.js.map

package/dist/staged-upload/hmac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.js","sourceRoot":"","sources":["../../src/staged-upload/hmac.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,MAAM,UAAU,mBAAmB;IACjC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,EAAE,IAAI,EAAE,CAAC;IACjE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,QAAgB,EAAE,MAAc,EAAE,GAAW;IACvF,OAAO,GAAG,QAAQ,IAAI,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,MAAc,EACd,GAAW,EACX,MAAc;IAEd,MAAM,OAAO,GAAG,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACnE,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,MAAc,EACd,GAAW,EACX,GAAW,EACX,MAAc;IAEd,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1C,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;YAC5C,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,MAAc,EACd,QAAgB,EAChB,MAAc,EACd,GAAW,EACX,MAAc;IAEd,MAAM,GAAG,GAAG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,EAAE,EAAE,QAAQ;QACZ,GAAG,EAAE,MAAM;QACX,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC;QAChB,GAAG;KACJ,CAAC,CAAC;IACH,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,sBAAsB,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC/E,CAAC"}

package/dist/staged-upload/limits.d.ts

@@ -0,0 +1,6 @@
+/** Hosted Vercel body limit — keep under platform ~4.5 MB ceiling. */
+export declare const HOSTED_STAGED_MAX_BYTES: number;
+export declare const STAGED_UPLOAD_TTL_SECONDS: number;
+export declare const STAGED_UPLOAD_RATE_LIMIT_PER_HOUR = 30;
+export declare function hostedStagedMaxBytes(): number;
+//# sourceMappingURL=limits.d.ts.map

package/dist/staged-upload/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/staged-upload/limits.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,QAAkB,CAAC;AAEvD,eAAO,MAAM,yBAAyB,QAAU,CAAC;AAEjD,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/staged-upload/limits.js

@@ -0,0 +1,9 @@
+import { MAX_UPLOAD_BYTES } from '../contentful/upload-limits.js';
+/** Hosted Vercel body limit — keep under platform ~4.5 MB ceiling. */
+export const HOSTED_STAGED_MAX_BYTES = 4 * 1024 * 1024;
+export const STAGED_UPLOAD_TTL_SECONDS = 15 * 60;
+export const STAGED_UPLOAD_RATE_LIMIT_PER_HOUR = 30;
+export function hostedStagedMaxBytes() {
+    return Math.min(MAX_UPLOAD_BYTES, HOSTED_STAGED_MAX_BYTES);
+}
+//# sourceMappingURL=limits.js.map

package/dist/staged-upload/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/staged-upload/limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvD,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,EAAE,CAAC;AAEjD,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAEpD,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAAC;AAC7D,CAAC"}

package/dist/staged-upload/mime.d.ts

@@ -0,0 +1,2 @@
+export declare function isAllowedStagedMimeType(mimeType: string): boolean;
+//# sourceMappingURL=mime.d.ts.map

package/dist/staged-upload/mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../src/staged-upload/mime.ts"],"names":[],"mappings":"AAAA,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAUjE"}

package/dist/staged-upload/mime.js

@@ -0,0 +1,10 @@
+export function isAllowedStagedMimeType(mimeType) {
+    const normalized = mimeType.trim().toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    return (normalized.startsWith('image/') ||
+        normalized.startsWith('video/') ||
+        normalized === 'application/pdf');
+}
+//# sourceMappingURL=mime.js.map

package/dist/staged-upload/mime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.js","sourceRoot":"","sources":["../../src/staged-upload/mime.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,CACL,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC;QAC/B,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC;QAC/B,UAAU,KAAK,iBAAiB,CACjC,CAAC;AACJ,CAAC"}

package/dist/staged-upload/request.d.ts

@@ -0,0 +1,11 @@
+import type { StagedUploadStore } from './store.js';
+import type { StagedUploadRequestResult } from './types.js';
+export interface CreateStagedUploadRequestParams {
+    userId: string;
+    fileName: string;
+    mimeType: string;
+    byteLength?: number;
+    title?: string;
+}
+export declare function createStagedUploadRequest(store: StagedUploadStore, params: CreateStagedUploadRequestParams): Promise<StagedUploadRequestResult>;
+//# sourceMappingURL=request.d.ts.map

package/dist/staged-upload/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/staged-upload/request.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,+BAA+B,GACtC,OAAO,CAAC,yBAAyB,CAAC,CAoCpC"}

package/dist/staged-upload/request.js

@@ -0,0 +1,40 @@
+import { getPublicOrigin } from '../hosted/oauth/config.js';
+import { buildStagedUploadUrl, getUploadHmacSecret } from './hmac.js';
+import { hostedStagedMaxBytes, STAGED_UPLOAD_TTL_SECONDS } from './limits.js';
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export async function createStagedUploadRequest(store, params) {
+    const uploadId = await store.createPending({
+        userId: params.userId,
+        fileName: params.fileName,
+        mimeType: params.mimeType,
+        byteLength: params.byteLength,
+    });
+    const secret = getUploadHmacSecret();
+    const origin = getPublicOrigin();
+    const exp = Math.floor(Date.now() / 1000) + STAGED_UPLOAD_TTL_SECONDS;
+    const uploadUrl = buildStagedUploadUrl(origin, uploadId, params.userId, exp, secret);
+    const consumeArgs = [
+        'asset',
+        'upload',
+        '--staged',
+        uploadId,
+        '--mime',
+        params.mimeType,
+        '--file-name',
+        params.fileName,
+        ...(params.title ? ['--title', params.title] : []),
+    ];
+    const curlCommand = `curl -f -X POST -F ${shellQuote(`file=@/path/to/${params.fileName}`)} ${shellQuote(uploadUrl)}`;
+    return {
+        uploadId,
+        uploadUrl,
+        expiresIn: STAGED_UPLOAD_TTL_SECONDS,
+        expiresAt: exp,
+        maxBytes: hostedStagedMaxBytes(),
+        curlCommand,
+        consumeArgs,
+    };
+}
+//# sourceMappingURL=request.js.map

package/dist/staged-upload/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/staged-upload/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAY9E,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAwB,EACxB,MAAuC;IAEvC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC;QACzC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,yBAAyB,CAAC;IACtE,MAAM,SAAS,GAAG,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAErF,MAAM,WAAW,GAAG;QAClB,OAAO;QACP,QAAQ;QACR,UAAU;QACV,QAAQ;QACR,QAAQ;QACR,MAAM,CAAC,QAAQ;QACf,aAAa;QACb,MAAM,CAAC,QAAQ;QACf,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;IAEF,MAAM,WAAW,GAAG,sBAAsB,UAAU,CAAC,kBAAkB,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;IAErH,OAAO;QACL,QAAQ;QACR,SAAS;QACT,SAAS,EAAE,yBAAyB;QACpC,SAAS,EAAE,GAAG;QACd,QAAQ,EAAE,oBAAoB,EAAE;QAChC,WAAW;QACX,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/staged-upload/store.d.ts

@@ -0,0 +1,19 @@
+import type { RedisClient } from '../session/session-store.js';
+import type { StagedUploadConsumeResult, StagedUploadRecord } from './types.js';
+export declare class StagedUploadStore {
+    private readonly redis;
+    private readonly keyPrefix;
+    constructor(redis: RedisClient, keyPrefix?: string);
+    private fullKey;
+    assertRateLimit(userId: string): Promise<void>;
+    createPending(params: {
+        userId: string;
+        fileName: string;
+        mimeType: string;
+        byteLength?: number;
+    }): Promise<string>;
+    storeFile(userId: string, uploadId: string, buffer: Buffer, mimeType: string): Promise<StagedUploadRecord>;
+    consume(userId: string, uploadId: string): Promise<StagedUploadConsumeResult>;
+    getRecord(userId: string, uploadId: string): Promise<StagedUploadRecord | null>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/staged-upload/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/staged-upload/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAO/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA0BhF,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,KAAK,EAAE,WAAW,EAClB,SAAS,SAAa;IAGzC,OAAO,CAAC,OAAO;IAIT,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9C,aAAa,CAAC,MAAM,EAAE;QAC1B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IAqCb,SAAS,CACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC;IAgCxB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAuB7E,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAGtF"}

package/dist/staged-upload/store.js

@@ -0,0 +1,124 @@
+import * as crypto from 'node:crypto';
+import { assertUploadBufferSize } from '../contentful/upload-limits.js';
+import { hostedStagedMaxBytes, STAGED_UPLOAD_RATE_LIMIT_PER_HOUR, STAGED_UPLOAD_TTL_SECONDS, } from './limits.js';
+import { isAllowedStagedMimeType } from './mime.js';
+const KEY_PREFIX = 'cms-edit:staged:';
+const RATE_PREFIX = 'cms-edit:staged-rate:';
+function rateKey(userId, hourBucket) {
+    return `${RATE_PREFIX}${userId}:${String(hourBucket)}`;
+}
+function parseRecord(raw) {
+    if (!raw) {
+        return null;
+    }
+    if (typeof raw === 'string') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof raw === 'object') {
+        return raw;
+    }
+    return null;
+}
+export class StagedUploadStore {
+    redis;
+    keyPrefix;
+    constructor(redis, keyPrefix = KEY_PREFIX) {
+        this.redis = redis;
+        this.keyPrefix = keyPrefix;
+    }
+    fullKey(userId, uploadId) {
+        return `${this.keyPrefix}${userId}:${uploadId}`;
+    }
+    async assertRateLimit(userId) {
+        const hourBucket = Math.floor(Date.now() / (60 * 60 * 1000));
+        const key = rateKey(userId, hourBucket);
+        const count = await this.redis.incr(key);
+        if (count === 1) {
+            await this.redis.expire(key, 60 * 60);
+        }
+        if (count > STAGED_UPLOAD_RATE_LIMIT_PER_HOUR) {
+            throw new Error(`Staged upload rate limit exceeded (${String(STAGED_UPLOAD_RATE_LIMIT_PER_HOUR)} per hour).`);
+        }
+    }
+    async createPending(params) {
+        if (!isAllowedStagedMimeType(params.mimeType)) {
+            throw new Error(`MIME type not allowed for staged upload: ${params.mimeType}`);
+        }
+        if (params.byteLength !== undefined && params.byteLength > hostedStagedMaxBytes()) {
+            throw new Error(`Declared byteLength exceeds hosted staged upload limit (${String(hostedStagedMaxBytes())} bytes).`);
+        }
+        await this.assertRateLimit(params.userId);
+        const uploadId = crypto.randomUUID().replace(/-/g, '');
+        const record = {
+            uploadId,
+            userId: params.userId,
+            fileName: params.fileName,
+            mimeType: params.mimeType,
+            byteLength: params.byteLength,
+            status: 'pending',
+            createdAt: Date.now(),
+        };
+        const set = await this.redis.set(this.fullKey(params.userId, uploadId), JSON.stringify(record), {
+            ex: STAGED_UPLOAD_TTL_SECONDS,
+            nx: true,
+        });
+        if (set !== true) {
+            throw new Error('Failed to reserve staged upload slot.');
+        }
+        return uploadId;
+    }
+    async storeFile(userId, uploadId, buffer, mimeType) {
+        assertUploadBufferSize(buffer);
+        if (buffer.length > hostedStagedMaxBytes()) {
+            throw new Error(`File exceeds hosted staged upload limit (${String(hostedStagedMaxBytes())} bytes).`);
+        }
+        if (!isAllowedStagedMimeType(mimeType)) {
+            throw new Error(`MIME type not allowed for staged upload: ${mimeType}`);
+        }
+        const key = this.fullKey(userId, uploadId);
+        const existing = parseRecord(await this.redis.get(key));
+        if (!existing || existing.userId !== userId || existing.uploadId !== uploadId) {
+            throw new Error('Staged upload slot not found or expired.');
+        }
+        if (existing.status === 'ready') {
+            throw new Error('Staged upload already received.');
+        }
+        const record = {
+            ...existing,
+            status: 'ready',
+            mimeType,
+            byteLength: buffer.length,
+            dataBase64: buffer.toString('base64'),
+        };
+        await this.redis.set(key, JSON.stringify(record), { ex: STAGED_UPLOAD_TTL_SECONDS });
+        return record;
+    }
+    async consume(userId, uploadId) {
+        const key = this.fullKey(userId, uploadId);
+        const existing = parseRecord(await this.redis.get(key));
+        if (!existing || existing.userId !== userId || existing.uploadId !== uploadId) {
+            throw new Error('Staged upload not found or expired.');
+        }
+        if (existing.status !== 'ready' || !existing.dataBase64) {
+            throw new Error('Staged upload has no file data yet. POST the file to uploadUrl first.');
+        }
+        await this.redis.del(key);
+        const buffer = Buffer.from(existing.dataBase64, 'base64');
+        assertUploadBufferSize(buffer);
+        return {
+            buffer,
+            fileName: existing.fileName,
+            mimeType: existing.mimeType,
+            byteLength: buffer.length,
+        };
+    }
+    async getRecord(userId, uploadId) {
+        return parseRecord(await this.redis.get(this.fullKey(userId, uploadId)));
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/staged-upload/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/staged-upload/store.ts"],"names":[],"mappings":"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"}

package/dist/staged-upload/types.d.ts

@@ -0,0 +1,27 @@
+export type StagedUploadStatus = 'pending' | 'ready';
+export interface StagedUploadRecord {
+    uploadId: string;
+    userId: string;
+    fileName: string;
+    mimeType: string;
+    byteLength?: number;
+    status: StagedUploadStatus;
+    dataBase64?: string;
+    createdAt: number;
+}
+export interface StagedUploadRequestResult {
+    uploadId: string;
+    uploadUrl: string;
+    expiresIn: number;
+    expiresAt: number;
+    maxBytes: number;
+    curlCommand: string;
+    consumeArgs: string[];
+}
+export interface StagedUploadConsumeResult {
+    buffer: Buffer;
+    fileName: string;
+    mimeType: string;
+    byteLength: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/staged-upload/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/staged-upload/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/staged-upload/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/staged-upload/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/staged-upload/types.ts"],"names":[],"mappings":""}

package/docs/editor-tasks/media-reuse-and-upload.md

@@ -14,7 +14,7 @@
 ## Prerequisites
 
 - **Always run `index sync` first** if the catalog may be stale
-- On **hosted MCP**, the server has **no filesystem** — use `--base64` or `--url` only (never a local file path in `args`)
+- On **hosted MCP**, the server has **no filesystem** — use **staged upload**, `--base64`, or `--url` (never a local file path in `args`)
 
 ## Reuse-first workflow (default)
 
@@ -29,21 +29,28 @@
 
 ### Hosted MCP (default)
 
-**Prefer `--base64`** with the **actual encoded file bytes** in the `args` array:
+**Prefer staged upload** for files larger than ~500 KB or when base64 in `cms_edit` args fails (agent harness message limits):
 
-```
-cms_edit ["asset", "upload", "--base64", "<encoded-bytes>", "--mime", "image/png", "--file-name", "headshot-name-1200.png", "--title", "Headshot — Name", "--alt", "Descriptive alt text"]
-```
+1. `cms_edit_request_staged_upload` with `fileName`, `mimeType`, optional `byteLength`, optional `title`
+2. Run the returned `curlCommand` in a shell (POST file to `uploadUrl`)
+3. `cms_edit` with the returned `consumeArgs` (e.g. `["asset","upload","--staged","<uploadId>",…]`)
 
 Rules:
 
-- **`--mime` and `--file-name` are required** with `--base64`
-- Pass **raw base64 text** — not a filesystem path, not `file:///…`, not a placeholder
+- Staged upload keeps binary **out of MCP args** — only a short `uploadId` is passed to Contentful
+- Hosted limit: **4 MB** per file; TTL **15 minutes**; single-use
 - **PNG** when the source has transparency (portraits on brand-colour cards); JPEG flattens alpha
-- **Stress-tested:** ~2 MB PNG (~2.8 MB base64) uploads successfully on hosted `pedestal-cms-edit` (Jun 2026)
 - Upload alone does **not** attach the asset — follow with **link + save** (below)
 
-**Fallback `--url`** only when base64 is impractical (agent message limits, very large files):
+**Small files:** `--base64` with actual encoded bytes in `args` when the harness accepts the payload:
+
+```
+cms_edit ["asset", "upload", "--base64", "<encoded-bytes>", "--mime", "image/png", "--file-name", "icon.png", "--title", "…"]
+```
+
+Pass **raw base64 text** — not a filesystem path, not `file:///…`.
+
+**Last resort `--url`** only when staged upload and base64 are impractical:
 
 ```
 cms_edit ["asset", "upload", "--url", "https://<public-https-url>/file.png", "--mime", "image/png", "--file-name", "headshot-name-1200.png", "--title", "…"]

package/docs/mcp/hosted-guide.md

@@ -20,6 +20,7 @@ All `save` operations create **drafts only**. A human must review and publish in
 | Tool | Purpose |
 |------|---------|
 | `cms_edit` | Run any cms-edit command via an `args` array |
+| `cms_edit_request_staged_upload` | Get a presigned upload URL for large files (then `curl` + `asset upload --staged`) |
 | `cms_edit_version` | Check the installed cms-edit version (no session required) |
 | `cms_edit_help` | Read this guide by topic (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) |
 
@@ -136,19 +137,31 @@ cms-edit saves **drafts only**. A colleague must **publish in Contentful** for c
 
 Hosted connectors have **no server filesystem**. Use one source per upload:
 
-| Source | Example |
-|--------|---------|
-| **`--base64`** (preferred) | `["asset", "upload", "--base64", "<bytes>", "--mime", "image/png", "--file-name", "photo.png", "--title", "…"]` |
-| **`--url`** (fallback) | `["asset", "upload", "--url", "https://…/photo.png", "--mime", "image/png", "--file-name", "photo.png"]` |
+| Source | When | Example |
+|--------|------|---------|
+| **Staged upload** (preferred for files &gt;~500 KB) | Agent harness cannot pass large base64 in `cms_edit` args | See **Staged upload** below |
+| **`--base64`** | Small files when inline base64 works | `["asset", "upload", "--base64", "<bytes>", "--mime", "image/png", "--file-name", "photo.png"]` |
+| **`--url`** (last resort) | Public HTTPS URL fetchable by the host | `["asset", "upload", "--url", "https://…/photo.png", "--mime", "image/png", "--file-name", "photo.png"]` |
 
 **Required with `--base64`:** `--mime`, `--file-name`. Pass **encoded bytes** in `args` — never a local path (`./file.png`, `file:///tmp/…`) or placeholder string.
 
 **After upload:** note the returned asset `id`, attach to the entry (`asset set @root media <id>` for person portraits), then `diff` → `save`. Upload alone does not update entries.
 
-**PNG** when transparency matters. Verified on production hosts: ~2 MB PNG (~2.8 MB base64) succeeds; very large files may need `--url` from public HTTPS.
+**PNG** when transparency matters.
 
 Full workflow: `cms-edit://customer/task-media-reuse-and-upload`.
 
+### Staged upload (large files)
+
+Keeps bulk binary **out of MCP tool args**. The agent uploads via `curl`, then passes only a short `uploadId`.
+
+1. `cms_edit_request_staged_upload` with `fileName`, `mimeType`, optional `byteLength`, optional `title`
+2. Run the returned `curlCommand` in a shell (POST multipart to `uploadUrl`)
+3. `cms_edit` with the returned `consumeArgs` (includes `asset upload --staged <uploadId>`)
+4. Link and save as usual
+
+Hosted limit: **4 MB** per staged file (Vercel body limit). TTL: **15 minutes**, single-use.
+
 ## Featured images (articles)
 
 Read `cms-edit://customer/defaults` when present. Otherwise:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",

package/skills/core/SKILL.md

@@ -369,11 +369,14 @@ cms-edit asset search "hero background"
 cms-edit asset search --filename istockphoto-123.jpg
 cms-edit asset search --filename-match 'istockphoto-.*'
 
-# Upload from local file, URL, or base64
+# Upload from local file, URL, base64, or staged ref (hosted MCP)
 cms-edit asset upload ./poster.jpg --title "Poster"
 cms-edit asset upload --url https://example.com/image.jpg --if-exists-by-filename
 cms-edit asset upload --base64 "$B64" --mime image/png --file-name poster.png
 
+# Hosted MCP — large files: cms_edit_request_staged_upload → curl uploadUrl → consumeArgs
+# cms_edit ["asset", "upload", "--staged", "<uploadId>", "--mime", "image/png", "--file-name", "photo.png"]
+
 # Upload and create a Media wrapper in one step
 cms-edit asset upload ./figure.png --with-media --media-name "Figure 1" --media-position Middle