feat: make presigned URL expiry configurable via BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS

- Add `BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS` to env.ts Zod schema
  (default 7200s / 2 hours, range 60–604800)
- Replace hardcoded `DEFAULT_PRESIGNED_EXPIRY_SECONDS` constant in
  s3-provider.ts with env var lookup
- Update tests to use env var in mocks and verify new default
- Add env var to .env.example files and deployment docs

Author: pullfrog[bot]

.env.example

@@ -212,4 +212,6 @@ BLOB_STORAGE_LOCAL_PATH=.blob-storage
 # Custom endpoint URL. Often required for non-AWS providers (R2, MinIO, B2, Spaces, etc.).
 # BLOB_STORAGE_S3_ENDPOINT=
 # Path-style URLs. Default false for AWS S3. Some S3-compatible providers require true.
-# BLOB_STORAGE_S3_FORCE_PATH_STYLE=false
+# BLOB_STORAGE_S3_FORCE_PATH_STYLE=false
+# Expiry in seconds for S3 presigned media URLs. Default 7200 (2 hours). Range: 60–604800.
+# BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS=7200

agents-api/src/domains/run/services/__tests__/s3-provider.test.ts

@@ -118,6 +118,7 @@ describe('S3BlobStorageProvider', () => {
         BLOB_STORAGE_S3_ACCESS_KEY_ID: 'key',
         BLOB_STORAGE_S3_SECRET_ACCESS_KEY: 'secret',
         BLOB_STORAGE_S3_FORCE_PATH_STYLE: true,
+        BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS: 7200,
       },
     }));
 
@@ -129,7 +130,7 @@ describe('S3BlobStorageProvider', () => {
 
     expect(url).toBe('https://bucket.s3.us-east-1.amazonaws.com/key?signed=true');
     expect(getSignedUrl).toHaveBeenCalledWith(expect.anything(), expect.anything(), {
-      expiresIn: 3600,
+      expiresIn: 7200,
     });
   });
 
@@ -142,17 +143,18 @@ describe('S3BlobStorageProvider', () => {
         BLOB_STORAGE_S3_ACCESS_KEY_ID: 'key',
         BLOB_STORAGE_S3_SECRET_ACCESS_KEY: 'secret',
         BLOB_STORAGE_S3_FORCE_PATH_STYLE: true,
+        BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS: 7200,
       },
     }));
 
     const { S3BlobStorageProvider } = await import('../blob-storage/s3-provider');
     const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
     const provider = new S3BlobStorageProvider();
 
-    await provider.getPresignedUrl('v1/t_tenant/media/file.png', 7200);
+    await provider.getPresignedUrl('v1/t_tenant/media/file.png', 900);
 
     expect(getSignedUrl).toHaveBeenCalledWith(expect.anything(), expect.anything(), {
-      expiresIn: 7200,
+      expiresIn: 900,
     });
   });
 
@@ -165,6 +167,7 @@ describe('S3BlobStorageProvider', () => {
         BLOB_STORAGE_S3_ACCESS_KEY_ID: 'key',
         BLOB_STORAGE_S3_SECRET_ACCESS_KEY: 'secret',
         BLOB_STORAGE_S3_FORCE_PATH_STYLE: true,
+        BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS: 7200,
       },
     }));
 

agents-api/src/domains/run/services/blob-storage/s3-provider.ts

@@ -15,7 +15,6 @@ import type {
 } from './types';
 
 const logger = getLogger('S3BlobStorageProvider');
-const DEFAULT_PRESIGNED_EXPIRY_SECONDS = 3600;
 
 export class S3BlobStorageProvider implements BlobStorageProvider {
   private client: S3Client;
@@ -120,7 +119,7 @@ export class S3BlobStorageProvider implements BlobStorageProvider {
   }
 
   async getPresignedUrl(key: string, expiresInSeconds?: number): Promise<string> {
-    const expiry = expiresInSeconds ?? DEFAULT_PRESIGNED_EXPIRY_SECONDS;
+    const expiry = expiresInSeconds ?? env.BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS;
     logger.debug({ key, expiry }, 'Generating presigned URL');
     try {
       return await getSignedUrl(

agents-api/src/env.ts

@@ -294,6 +294,16 @@ const envSchema = z
       .describe(
         'Force path-style S3 URLs: false for AWS S3 (default), true for path-style/self-hosted S3-compatible.'
       ),
+    BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS: z.coerce
+      .number()
+      .int()
+      .min(60)
+      .max(604800)
+      .optional()
+      .default(7200)
+      .describe(
+        'Expiry in seconds for S3 presigned media URLs. Must be between 60 and 604800 (7 days). Default 7200 (2 hours).'
+      ),
   })
   .superRefine((data, ctx) => {
     const hasS3Bucket =

agents-docs/content/deployment/add-other-services/s3-blob-storage.mdx

@@ -13,7 +13,7 @@ The Inkeep Agent Framework stores file attachments (images, PDFs, documents) upl
 When S3 is configured, media URLs in conversation responses are **presigned S3 URLs** — clients fetch files directly from S3 with no proxy overhead. This provides:
 - **Zero-proxy delivery** — clients talk directly to S3, no function invocations for media reads
 - **Domain isolation** — media is served from `*.s3.amazonaws.com`, separate from your API domain
-- **Time-limited access** — presigned URLs expire after 1 hour
+- **Time-limited access** — presigned URLs expire after 2 hours (configurable via `BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS`)
 
 When S3 is not configured, the framework falls back to the local filesystem with a server-side media proxy.
 
@@ -68,6 +68,16 @@ BLOB_STORAGE_S3_ENDPOINT=https://your-custom-endpoint
 BLOB_STORAGE_S3_FORCE_PATH_STYLE=true
 ```
 
+### Optional: Presigned URL Expiry
+
+By default, presigned URLs expire after 2 hours (7200 seconds). To customize:
+
+```bash
+BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS=900  # 15 minutes
+```
+
+Accepted range: 60–604800 (1 minute to 7 days).
+
 ## Storage Backend Priority
 
 The framework selects a storage backend based on which environment variables are set:
@@ -86,5 +96,5 @@ Changing the storage backend after files have been uploaded will make previously
 
 1. When a user sends a file attachment in a chat message, the file is uploaded to S3 using the configured credentials
 2. The file's location is stored in the database as an internal blob URI
-3. When conversation history is retrieved, blob URIs are resolved to presigned S3 URLs with a 1-hour expiry
+3. When conversation history is retrieved, blob URIs are resolved to presigned S3 URLs (default 2-hour expiry, configurable via `BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS`)
 4. Clients fetch files directly from S3 using the presigned URL — no proxy needed

create-agents-template/.env.example

@@ -143,4 +143,6 @@ BLOB_STORAGE_LOCAL_PATH=.blob-storage
 # Custom endpoint URL. Often required for non-AWS providers (R2, MinIO, B2, Spaces, etc.).
 # BLOB_STORAGE_S3_ENDPOINT=
 # Path-style URLs. Default false for AWS S3. Some S3-compatible providers require true.
-# BLOB_STORAGE_S3_FORCE_PATH_STYLE=false
+# BLOB_STORAGE_S3_FORCE_PATH_STYLE=false
+# Expiry in seconds for S3 presigned media URLs. Default 7200 (2 hours). Range: 60–604800.
+# BLOB_STORAGE_PRESIGNED_URL_EXPIRY_SECONDS=7200