@open-mercato/storage-s3 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/dist/modules/storage_s3/workers/quota-recovery.js

@@ -0,0 +1,70 @@
+import { S3StorageDriver } from "../lib/s3-driver.js";
+import { scheduleStorageS3QuotaRecovery } from "../lib/quota-recovery-queue.js";
+const metadata = {
+  queue: "storage-s3-quota-recovery",
+  id: "storage_s3:quota-recovery",
+  concurrency: 2
+};
+async function handle(job, ctx) {
+  const quotaService = ctx.resolve("attachmentQuotaService");
+  const scope = {
+    tenantId: job.payload.tenantId,
+    organizationId: job.payload.organizationId
+  };
+  const record = await quotaService.getReservation(job.payload.reservationId, scope);
+  if (!record || record.status === "committed") return;
+  if (record.expiresAt && record.expiresAt.getTime() > Date.now()) {
+    await scheduleStorageS3QuotaRecovery(job.payload, record.expiresAt.getTime() - Date.now());
+    return;
+  }
+  const claimed = await quotaService.claimExpired(record.id, scope);
+  if (!claimed) return;
+  try {
+    const credentialsService = ctx.resolve("integrationCredentialsService");
+    const credentials = await credentialsService.resolve("storage_s3", {
+      tenantId: claimed.tenantId,
+      organizationId: claimed.organizationId
+    });
+    if (!credentials) throw new Error("S3 integration is not configured for quota recovery.");
+    const driver = new S3StorageDriver({
+      ...credentials,
+      organizationId: claimed.organizationId,
+      tenantId: claimed.tenantId
+    });
+    if (claimed.source === "storage_s3_signed") {
+      const listed = await driver.listObjects(claimed.storagePath, 1);
+      const object = listed.files.find((file) => file.key === claimed.storagePath);
+      if (!object) {
+        if (record.status === "storing" && (job.payload.absenceCheck ?? 0) === 0 && claimed.expiresAt) {
+          await scheduleStorageS3QuotaRecovery(
+            {
+              ...job.payload,
+              absenceCheck: 1
+            },
+            claimed.expiresAt.getTime() - Date.now()
+          );
+          return;
+        }
+        await quotaService.release(claimed.id, claimed.leaseToken);
+        return;
+      }
+      const validSize = claimed.uploadTokenHash ? object.size <= claimed.reservedBytes : object.size === claimed.reservedBytes;
+      if (validSize) {
+        await quotaService.commitRecoveredStandalone(claimed.id, claimed.leaseToken, object.size);
+        return;
+      }
+    }
+    await driver.deleteStrict("", claimed.storagePath);
+    await quotaService.release(claimed.id, claimed.leaseToken);
+  } catch (error) {
+    if (claimed.expiresAt) {
+      await scheduleStorageS3QuotaRecovery(job.payload, claimed.expiresAt.getTime() - Date.now());
+    }
+    throw error;
+  }
+}
+export {
+  handle as default,
+  metadata
+};
+//# sourceMappingURL=quota-recovery.js.map

package/dist/modules/storage_s3/workers/quota-recovery.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/storage_s3/workers/quota-recovery.ts"],
+  "sourcesContent": ["import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'\nimport type { AttachmentQuotaService } from '@open-mercato/core/modules/attachments/lib/quota-service'\nimport { S3StorageDriver } from '../lib/s3-driver'\nimport { scheduleStorageS3QuotaRecovery, type StorageS3QuotaRecoveryJob } from '../lib/quota-recovery-queue'\n\nexport const metadata: WorkerMeta = {\n  queue: 'storage-s3-quota-recovery',\n  id: 'storage_s3:quota-recovery',\n  concurrency: 2,\n}\n\ntype HandlerContext = JobContext & { resolve: <T = unknown>(name: string) => T }\n\ntype IntegrationCredentialsService = {\n  resolve(integrationId: string, scope: { tenantId: string; organizationId: string }): Promise<Record<string, unknown> | null>\n}\n\nexport default async function handle(\n  job: QueuedJob<StorageS3QuotaRecoveryJob>,\n  ctx: HandlerContext,\n): Promise<void> {\n  const quotaService = ctx.resolve<AttachmentQuotaService>('attachmentQuotaService')\n  const scope = {\n    tenantId: job.payload.tenantId,\n    organizationId: job.payload.organizationId,\n  }\n  const record = await quotaService.getReservation(job.payload.reservationId, scope)\n  if (!record || record.status === 'committed') return\n  if (record.expiresAt && record.expiresAt.getTime() > Date.now()) {\n    await scheduleStorageS3QuotaRecovery(job.payload, record.expiresAt.getTime() - Date.now())\n    return\n  }\n\n  const claimed = await quotaService.claimExpired(record.id, scope)\n  if (!claimed) return\n  try {\n    const credentialsService = ctx.resolve<IntegrationCredentialsService>('integrationCredentialsService')\n    const credentials = await credentialsService.resolve('storage_s3', {\n      tenantId: claimed.tenantId,\n      organizationId: claimed.organizationId,\n    })\n    if (!credentials) throw new Error('S3 integration is not configured for quota recovery.')\n    const driver = new S3StorageDriver({\n      ...credentials,\n      organizationId: claimed.organizationId,\n      tenantId: claimed.tenantId,\n    })\n\n    if (claimed.source === 'storage_s3_signed') {\n      const listed = await driver.listObjects(claimed.storagePath, 1)\n      const object = listed.files.find((file) => file.key === claimed.storagePath)\n      if (!object) {\n        if (record.status === 'storing' && (job.payload.absenceCheck ?? 0) === 0 && claimed.expiresAt) {\n          await scheduleStorageS3QuotaRecovery({\n            ...job.payload,\n            absenceCheck: 1,\n          },\n            claimed.expiresAt.getTime() - Date.now(),\n          )\n          return\n        }\n        await quotaService.release(claimed.id, claimed.leaseToken)\n        return\n      }\n      const validSize = claimed.uploadTokenHash\n        ? object.size <= claimed.reservedBytes\n        : object.size === claimed.reservedBytes\n      if (validSize) {\n        await quotaService.commitRecoveredStandalone(claimed.id, claimed.leaseToken, object.size)\n        return\n      }\n    }\n\n    await driver.deleteStrict('', claimed.storagePath)\n    await quotaService.release(claimed.id, claimed.leaseToken)\n  } catch (error) {\n    if (claimed.expiresAt) {\n      await scheduleStorageS3QuotaRecovery(job.payload, claimed.expiresAt.getTime() - Date.now())\n    }\n    throw error\n  }\n}\n"],
+  "mappings": "AAEA,SAAS,uBAAuB;AAChC,SAAS,sCAAsE;AAExE,MAAM,WAAuB;AAAA,EAClC,OAAO;AAAA,EACP,IAAI;AAAA,EACJ,aAAa;AACf;AAQA,eAAO,OACL,KACA,KACe;AACf,QAAM,eAAe,IAAI,QAAgC,wBAAwB;AACjF,QAAM,QAAQ;AAAA,IACZ,UAAU,IAAI,QAAQ;AAAA,IACtB,gBAAgB,IAAI,QAAQ;AAAA,EAC9B;AACA,QAAM,SAAS,MAAM,aAAa,eAAe,IAAI,QAAQ,eAAe,KAAK;AACjF,MAAI,CAAC,UAAU,OAAO,WAAW,YAAa;AAC9C,MAAI,OAAO,aAAa,OAAO,UAAU,QAAQ,IAAI,KAAK,IAAI,GAAG;AAC/D,UAAM,+BAA+B,IAAI,SAAS,OAAO,UAAU,QAAQ,IAAI,KAAK,IAAI,CAAC;AACzF;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,aAAa,aAAa,OAAO,IAAI,KAAK;AAChE,MAAI,CAAC,QAAS;AACd,MAAI;AACF,UAAM,qBAAqB,IAAI,QAAuC,+BAA+B;AACrG,UAAM,cAAc,MAAM,mBAAmB,QAAQ,cAAc;AAAA,MACjE,UAAU,QAAQ;AAAA,MAClB,gBAAgB,QAAQ;AAAA,IAC1B,CAAC;AACD,QAAI,CAAC,YAAa,OAAM,IAAI,MAAM,sDAAsD;AACxF,UAAM,SAAS,IAAI,gBAAgB;AAAA,MACjC,GAAG;AAAA,MACH,gBAAgB,QAAQ;AAAA,MACxB,UAAU,QAAQ;AAAA,IACpB,CAAC;AAED,QAAI,QAAQ,WAAW,qBAAqB;AAC1C,YAAM,SAAS,MAAM,OAAO,YAAY,QAAQ,aAAa,CAAC;AAC9D,YAAM,SAAS,OAAO,MAAM,KAAK,CAAC,SAAS,KAAK,QAAQ,QAAQ,WAAW;AAC3E,UAAI,CAAC,QAAQ;AACX,YAAI,OAAO,WAAW,cAAc,IAAI,QAAQ,gBAAgB,OAAO,KAAK,QAAQ,WAAW;AAC7F,gBAAM;AAAA,YAA+B;AAAA,cACnC,GAAG,IAAI;AAAA,cACP,cAAc;AAAA,YAChB;AAAA,YACE,QAAQ,UAAU,QAAQ,IAAI,KAAK,IAAI;AAAA,UACzC;AACA;AAAA,QACF;AACA,cAAM,aAAa,QAAQ,QAAQ,IAAI,QAAQ,UAAU;AACzD;AAAA,MACF;AACA,YAAM,YAAY,QAAQ,kBACtB,OAAO,QAAQ,QAAQ,gBACvB,OAAO,SAAS,QAAQ;AAC5B,UAAI,WAAW;AACb,cAAM,aAAa,0BAA0B,QAAQ,IAAI,QAAQ,YAAY,OAAO,IAAI;AACxF;AAAA,MACF;AAAA,IACF;AAEA,UAAM,OAAO,aAAa,IAAI,QAAQ,WAAW;AACjD,UAAM,aAAa,QAAQ,QAAQ,IAAI,QAAQ,UAAU;AAAA,EAC3D,SAAS,OAAO;AACd,QAAI,QAAQ,WAAW;AACrB,YAAM,+BAA+B,IAAI,SAAS,QAAQ,UAAU,QAAQ,IAAI,KAAK,IAAI,CAAC;AAAA,IAC5F;AACA,UAAM;AAAA,EACR;AACF;",
+  "names": []
+}

package/jest.config.cjs

@@ -9,6 +9,7 @@ module.exports = {
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
   moduleNameMapper: {
     '^@open-mercato/core/(.*)$': '<rootDir>/../core/src/$1',
+    '^@open-mercato/queue$': '<rootDir>/../queue/src/index.ts',
     '^@open-mercato/shared/(.*)$': '<rootDir>/../shared/src/$1',
   },
   transform: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/storage-s3",
-  "version": "0.6.7",
+  "version": "0.6.8-develop.6874.1.982d6097d8",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,7 @@
       "types": "./src/*.ts",
       "default": "./dist/*.js"
     },
+    "./*.json": "./src/*.json",
     "./*": {
       "types": [
         "./src/*.ts",
@@ -23,6 +24,7 @@
       ],
       "default": "./dist/*.js"
     },
+    "./*/*.json": "./src/*/*.json",
     "./*/*": {
       "types": [
         "./src/*/*.ts",
@@ -30,6 +32,7 @@
       ],
       "default": "./dist/*/*.js"
     },
+    "./*/*/*.json": "./src/*/*/*.json",
     "./*/*/*": {
       "types": [
         "./src/*/*/*.ts",
@@ -37,6 +40,7 @@
       ],
       "default": "./dist/*/*/*.js"
     },
+    "./*/*/*/*.json": "./src/*/*/*/*.json",
     "./*/*/*/*": {
       "types": [
         "./src/*/*/*/*.ts",
@@ -44,6 +48,7 @@
       ],
       "default": "./dist/*/*/*/*.js"
     },
+    "./*/*/*/*/*.json": "./src/*/*/*/*/*.json",
     "./*/*/*/*/*": {
       "types": [
         "./src/*/*/*/*/*.ts",
@@ -69,19 +74,20 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1085.0",
     "@aws-sdk/s3-request-presigner": "^3.1085.0",
-    "@open-mercato/core": "0.6.7"
+    "@open-mercato/core": "0.6.8-develop.6874.1.982d6097d8",
+    "@open-mercato/queue": "0.6.8-develop.6874.1.982d6097d8"
   },
   "peerDependencies": {
     "@mikro-orm/postgresql": "^6.6.10",
-    "@open-mercato/shared": "0.6.7"
+    "@open-mercato/shared": "0.6.8-develop.6874.1.982d6097d8"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.7",
+    "@open-mercato/shared": "0.6.8-develop.6874.1.982d6097d8",
     "@types/jest": "^30.0.0",
     "esbuild": "^0.28.1",
     "glob": "^13.0.6",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11",
+    "ts-jest": "^29.4.12",
     "typescript": "7.0.2"
   },
   "publishConfig": {
@@ -91,5 +97,6 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/storage-s3"
-  }
+  },
+  "stableVersion": "0.6.7"
 }

package/src/modules/storage_s3/__tests__/endpoint-safety.test.ts

@@ -0,0 +1,71 @@
+/** @jest-environment node */
+
+import { createSafeS3EndpointLookup, UnsafeS3EndpointError } from '../lib/endpoint-safety'
+
+function runLookup(
+  lookup: NonNullable<ReturnType<typeof createSafeS3EndpointLookup>>,
+  hostname: string,
+): Promise<{ address: string; family: number | undefined }> {
+  return new Promise((resolve, reject) => {
+    lookup(hostname, {}, (err, address, family) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      if (typeof address !== 'string') {
+        reject(new Error('Expected a single lookup result'))
+        return
+      }
+      resolve({ address, family })
+    })
+  })
+}
+
+describe('S3 endpoint safety', () => {
+  it('validates the DNS result used by the AWS SDK lookup callback', async () => {
+    const lookupHost = jest
+      .fn()
+      .mockResolvedValueOnce([{ address: '93.184.216.34', family: 4 }])
+      .mockResolvedValueOnce([{ address: '169.254.169.254', family: 4 }])
+
+    const lookup = createSafeS3EndpointLookup('https://objects.example.com', { lookupHost })
+    expect(lookup).toBeDefined()
+
+    await expect(runLookup(lookup!, 'objects.example.com')).resolves.toEqual({
+      address: '93.184.216.34',
+      family: 4,
+    })
+    await expect(runLookup(lookup!, 'objects.example.com')).rejects.toMatchObject({
+      reason: 'private_ip_resolved',
+    })
+  })
+
+  it('validates virtual-hosted bucket endpoint hosts requested by the AWS SDK', async () => {
+    const lookupHost = jest.fn().mockResolvedValueOnce([{ address: '93.184.216.34', family: 4 }])
+    const lookup = createSafeS3EndpointLookup('https://objects.example.com', { lookupHost })
+
+    await expect(runLookup(lookup!, 'test-bucket.objects.example.com')).resolves.toEqual({
+      address: '93.184.216.34',
+      family: 4,
+    })
+
+    expect(lookupHost).toHaveBeenCalledWith('test-bucket.objects.example.com')
+  })
+
+  it('rejects virtual-hosted bucket endpoint hosts that resolve to private addresses', async () => {
+    const lookupHost = jest.fn().mockResolvedValueOnce([{ address: '169.254.169.254', family: 4 }])
+    const lookup = createSafeS3EndpointLookup('https://objects.example.com', { lookupHost })
+
+    await expect(runLookup(lookup!, 'test-bucket.objects.example.com')).rejects.toMatchObject({
+      reason: 'private_ip_resolved',
+    })
+  })
+
+  it('refuses lookup attempts for hosts other than the configured endpoint host', async () => {
+    const lookup = createSafeS3EndpointLookup('https://objects.example.com')
+
+    await expect(runLookup(lookup!, 'metadata.google.internal')).rejects.toBeInstanceOf(
+      UnsafeS3EndpointError,
+    )
+  })
+})

package/src/modules/storage_s3/__tests__/health.test.ts

@@ -0,0 +1,38 @@
+/** @jest-environment node */
+
+const mockSend = jest.fn()
+
+jest.mock('@aws-sdk/client-s3', () => ({
+  S3Client: jest.fn().mockImplementation(() => ({ send: mockSend })),
+  HeadBucketCommand: jest.fn().mockImplementation((params) => ({ _type: 'HeadBucket', ...params })),
+}))
+
+import { S3Client } from '@aws-sdk/client-s3'
+import { s3HealthCheck } from '../lib/health'
+
+const BASE_CREDENTIALS = {
+  bucket: 'test-bucket',
+  region: 'eu-central-1',
+  authMode: 'access_keys',
+  accessKeyId: 'AKID',
+  secretAccessKey: 'SECRET',
+}
+
+beforeEach(() => {
+  mockSend.mockReset()
+  ;(S3Client as jest.Mock).mockClear()
+})
+
+describe('s3HealthCheck', () => {
+  it('rejects link-local custom endpoints before probing the bucket', async () => {
+    const result = await s3HealthCheck.check({
+      ...BASE_CREDENTIALS,
+      endpoint: 'http://169.254.169.254/latest/meta-data/',
+    })
+
+    expect(result.status).toBe('unhealthy')
+    expect(result.message).toMatch(/private or reserved IP range/i)
+    expect(S3Client).not.toHaveBeenCalled()
+    expect(mockSend).not.toHaveBeenCalled()
+  })
+})

package/src/modules/storage_s3/__tests__/i18nPackageExports.test.ts

@@ -0,0 +1,13 @@
+import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+
+const packageRequire = createRequire(__filename)
+
+describe('storage_s3 locale package exports', () => {
+  it.each(['en', 'de', 'es', 'pl'] as const)('resolves the %s locale through the package export map', (locale) => {
+    const localePath = packageRequire.resolve(`@open-mercato/storage-s3/modules/storage_s3/i18n/${locale}.json`)
+    const translations = JSON.parse(readFileSync(localePath, 'utf8')) as Record<string, unknown>
+
+    expect(translations['storage_s3.errors.unauthorized']).toEqual(expect.any(String))
+  })
+})

package/src/modules/storage_s3/__tests__/quota-lifecycle.test.ts

@@ -0,0 +1,216 @@
+/** @jest-environment node */
+
+const mockPutObject = jest.fn(async () => {})
+const mockDelete = jest.fn(async () => {})
+const mockGetSignedUrl = jest.fn(async () => 'https://s3.test/signed')
+const mockListObjects = jest.fn(async () => ({ files: [], truncated: false }))
+const mockScheduleRecovery = jest.fn(async () => {})
+
+jest.mock('../lib/s3-driver', () => ({
+  S3StorageDriver: jest.fn().mockImplementation(() => ({
+    putObject: mockPutObject,
+    delete: mockDelete,
+    deleteStrict: mockDelete,
+    getSignedUrl: mockGetSignedUrl,
+    listObjects: mockListObjects,
+    getBucket: () => 'bucket',
+  })),
+}))
+
+const mockQuotaService = {
+  reconcileStandaloneObjects: jest.fn(async () => {}),
+  reserve: jest.fn(async () => ({ id: 'reservation-1', leaseToken: 'lease-1', expiresAt: new Date(Date.now() + 60_000) })),
+  claimPendingByUploadTokenHash: jest.fn(async () => null as Record<string, unknown> | null),
+  beginStorage: jest.fn(async () => {}),
+  markStored: jest.fn(async () => {}),
+  completeStandalone: jest.fn(async () => {}),
+  release: jest.fn(async () => {}),
+  releaseCommittedByPath: jest.fn(async () => {}),
+}
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: jest.fn(async () => ({
+    resolve: (key: string) => {
+      if (key === 'integrationCredentialsService') {
+        return { resolve: jest.fn(async () => ({ bucket: 'bucket', region: 'us-east-1' })) }
+      }
+      if (key === 'attachmentQuotaService') return mockQuotaService
+      if (key === 'storageS3QuotaRecoveryScheduler') return mockScheduleRecovery
+      return null
+    },
+  })),
+}))
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => ({
+  getAuthFromRequest: jest.fn(async () => ({ tenantId: 'tenant-1', orgId: 'org-1' })),
+}))
+
+function multipartRequest() {
+  const form = new FormData()
+  form.set('file', new File([new Uint8Array([1, 2, 3])], 'safe.pdf', { type: 'application/pdf' }))
+  return new Request('http://localhost/api/storage-providers/s3/upload', { method: 'POST', body: form })
+}
+
+describe('storage_s3 quota lifecycle', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    process.env.OM_ATTACHMENT_MAX_UPLOAD_MB = '5'
+    process.env.OM_ATTACHMENT_TENANT_QUOTA_MB = '10'
+  })
+
+  afterEach(() => {
+    delete process.env.OM_ATTACHMENT_MAX_UPLOAD_MB
+    delete process.env.OM_ATTACHMENT_TENANT_QUOTA_MB
+  })
+
+  it('routes multipart uploads through the shared reservation service', async () => {
+    const { POST } = await import('../api/post/storage-providers/s3/upload')
+    const response = await POST(multipartRequest())
+
+    expect(response.status).toBe(200)
+    expect(mockQuotaService.reserve).toHaveBeenCalledWith(expect.objectContaining({
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      bytes: 3,
+      source: 'storage_s3_upload',
+    }))
+    expect(mockQuotaService.completeStandalone).toHaveBeenCalledWith(
+      'reservation-1',
+      'lease-1',
+      3,
+    )
+    expect(mockScheduleRecovery).toHaveBeenCalledWith({
+      reservationId: 'reservation-1',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+    }, expect.any(Number))
+  })
+
+  it('releases multipart capacity when durable recovery cannot be scheduled', async () => {
+    mockScheduleRecovery.mockRejectedValueOnce(new Error('queue unavailable'))
+    const { POST } = await import('../api/post/storage-providers/s3/upload')
+
+    const response = await POST(multipartRequest())
+
+    expect(response.status).toBe(500)
+    expect(mockQuotaService.release).toHaveBeenCalledWith('reservation-1', 'lease-1')
+    expect(mockPutObject).not.toHaveBeenCalled()
+  })
+
+  it('reserves exact bytes before generating a signed upload URL', async () => {
+    const { POST } = await import('../api/post/storage-providers/s3/signed-url')
+    const key = 'uploads/org_org-1/tenant_tenant-1/safe.pdf'
+    const response = await POST(new Request('http://localhost/api/storage-providers/s3/signed-url', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key, operation: 'upload', contentType: 'application/pdf', size: 3 }),
+    }))
+
+    expect(response.status).toBe(200)
+    expect(mockQuotaService.reserve).toHaveBeenCalledWith(expect.objectContaining({
+      storagePath: key,
+      bytes: 3,
+      source: 'storage_s3_signed',
+    }))
+    expect(mockQuotaService.reconcileStandaloneObjects).toHaveBeenCalled()
+    expect(await response.json()).toEqual(expect.objectContaining({
+      reservationId: 'reservation-1',
+      url: expect.stringContaining('/api/storage-providers/s3/signed-upload/'),
+    }))
+  })
+
+  it('atomically consumes a compatibility token so replay cannot delete the winning object', async () => {
+    mockQuotaService.claimPendingByUploadTokenHash
+      .mockResolvedValueOnce({
+        id: 'reservation-1',
+        leaseToken: 'lease-claimed',
+        source: 'storage_s3_signed',
+        reservedBytes: 3,
+        storagePath: 'uploads/org_org-1/tenant_tenant-1/safe.pdf',
+        tenantId: 'tenant-1',
+        organizationId: 'org-1',
+      })
+      .mockResolvedValueOnce(null)
+    const { PUT } = await import('../api/put/storage-providers/s3/signed-upload/[token]')
+    const request = () => new Request('http://localhost/api/storage-providers/s3/signed-upload/token', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/pdf' },
+      body: new Uint8Array([1, 2, 3]),
+    })
+
+    const first = await PUT(request(), { params: { token: 'token' } })
+    const replay = await PUT(request(), { params: { token: 'token' } })
+
+    expect(first.status).toBe(200)
+    expect(replay.status).toBe(410)
+    expect(mockPutObject).toHaveBeenCalledTimes(1)
+    expect(mockDelete).not.toHaveBeenCalled()
+  })
+
+  it('stops a chunked compatibility upload as soon as it crosses the reserved bound', async () => {
+    mockQuotaService.claimPendingByUploadTokenHash.mockResolvedValueOnce({
+      id: 'reservation-1',
+      leaseToken: 'lease-claimed',
+      source: 'storage_s3_signed',
+      reservedBytes: 3,
+      storagePath: 'uploads/org_org-1/tenant_tenant-1/safe.pdf',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+    })
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new Uint8Array([1, 2]))
+        controller.enqueue(new Uint8Array([3, 4]))
+        controller.close()
+      },
+    })
+    const { PUT } = await import('../api/put/storage-providers/s3/signed-upload/[token]')
+    const response = await PUT(new Request('http://localhost/api/storage-providers/s3/signed-upload/token', {
+      method: 'PUT',
+      body: stream,
+      duplex: 'half',
+    } as RequestInit & { duplex: 'half' }), { params: { token: 'token' } })
+
+    expect(response.status).toBe(413)
+    expect(mockPutObject).not.toHaveBeenCalled()
+    expect(mockQuotaService.release).toHaveBeenCalledWith('reservation-1', 'lease-claimed')
+  })
+
+  it('removes committed quota only after standalone object deletion succeeds', async () => {
+    const { DELETE } = await import('../api/delete/storage-providers/s3/delete')
+    const key = 'uploads/org_org-1/tenant_tenant-1/safe.pdf'
+    const response = await DELETE(new Request('http://localhost/api/storage-providers/s3/delete', {
+      method: 'DELETE',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key }),
+    }))
+
+    expect(response.status).toBe(204)
+    expect(mockDelete).toHaveBeenCalled()
+    expect(mockQuotaService.releaseCommittedByPath).toHaveBeenCalledWith(expect.objectContaining({
+      tenantId: 'tenant-1',
+      storageDriver: 's3',
+      storagePath: key,
+    }))
+  })
+
+  it('releases a programmatic signed-url reservation when recovery scheduling fails', async () => {
+    const { createStorageService } = await import('../lib/storage-service')
+    const service = createStorageService({
+      bucket: 'bucket',
+      region: 'us-east-1',
+      quotaService: mockQuotaService as never,
+      quotaRecoveryScheduler: jest.fn(async () => {
+        throw new Error('queue unavailable')
+      }),
+    })
+
+    await expect(service.getSignedUrl({
+      key: 'uploads/org_org-1/tenant_tenant-1/safe.pdf',
+      operation: 'upload',
+      size: 3,
+      scope: { tenantId: 'tenant-1', organizationId: 'org-1' },
+    })).rejects.toThrow('queue unavailable')
+    expect(mockQuotaService.release).toHaveBeenCalledWith('reservation-1', 'lease-1')
+  })
+})

package/src/modules/storage_s3/__tests__/quota-recovery.test.ts

@@ -0,0 +1,83 @@
+/** @jest-environment node */
+
+const mockListObjects = jest.fn(async () => ({ files: [], truncated: false }))
+const mockScheduleRecovery = jest.fn(async () => {})
+
+jest.mock('../lib/s3-driver', () => ({
+  S3StorageDriver: jest.fn().mockImplementation(() => ({
+    listObjects: mockListObjects,
+    deleteStrict: jest.fn(async () => {}),
+  })),
+}))
+
+jest.mock('../lib/quota-recovery-queue', () => ({
+  scheduleStorageS3QuotaRecovery: mockScheduleRecovery,
+}))
+
+import handle from '../workers/quota-recovery'
+import { S3StorageDriver } from '../lib/s3-driver'
+
+function reservation(status: 'storing' | 'recovering') {
+  return {
+    id: 'reservation-1',
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    reservedBytes: 3,
+    actualBytes: null,
+    status,
+    source: 'storage_s3_signed',
+    storageDriver: 's3',
+    partitionCode: null,
+    storagePath: 'uploads/org_org-1/tenant_tenant-1/safe.pdf',
+    leaseToken: 'lease-1',
+    uploadTokenHash: 'token-hash',
+    expiresAt: new Date(Date.now() - 1_000),
+  }
+}
+
+describe('storage_s3 quota recovery', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('retains capacity and rechecks once when an active proxy upload has no visible object yet', async () => {
+    const current = reservation('storing')
+    const claimed = { ...reservation('recovering'), expiresAt: new Date(Date.now() + 60_000) }
+    const quotaService = {
+      getReservation: jest.fn(async () => current),
+      claimExpired: jest.fn(async () => claimed),
+      release: jest.fn(async () => {}),
+      commitRecoveredStandalone: jest.fn(async () => {}),
+    }
+    const ctx = {
+      resolve: (name: string) => {
+        if (name === 'attachmentQuotaService') return quotaService
+        if (name === 'integrationCredentialsService') {
+          return { resolve: jest.fn(async () => ({ bucket: 'bucket', region: 'us-east-1' })) }
+        }
+        throw new Error(`Unexpected dependency: ${name}`)
+      },
+    }
+
+    const payload = {
+      reservationId: current.id,
+      tenantId: current.tenantId,
+      organizationId: current.organizationId,
+    }
+    await handle({ payload, id: 'job-1' } as never, ctx as never)
+
+    expect(quotaService.getReservation).toHaveBeenCalledWith(current.id, {
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+    })
+    expect(S3StorageDriver).toHaveBeenCalledWith(expect.objectContaining({
+      organizationId: 'org-1',
+      tenantId: 'tenant-1',
+    }))
+    expect(mockScheduleRecovery).toHaveBeenCalledWith(
+      { ...payload, absenceCheck: 1 },
+      expect.any(Number),
+    )
+    expect(quotaService.release).not.toHaveBeenCalled()
+  })
+})