Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

fix(storage): support object-scoped connection probes

Timothy Yine088a63c00e3
diff --git a/apps/cloud/app/assets/cloud.css b/apps/cloud/app/assets/cloud.css
index af1472b2..594bce79 100644
--- a/apps/cloud/app/assets/cloud.css
+++ b/apps/cloud/app/assets/cloud.css
@@ -1621,6 +1621,11 @@
gap: 16px;
margin-top: 20px;
}
+.cf-media-workbench .cf-inline-controls .cf-button {
+ max-width: 100%;
+ min-width: 0;
+ white-space: normal;
+}
.cf-media-controls {
display: grid;
gap: 12px;
diff --git a/apps/cloud/app/components/CloudMediaWorkbench.vue b/apps/cloud/app/components/CloudMediaWorkbench.vue
index bc613746..5ff19b1e 100644
--- a/apps/cloud/app/components/CloudMediaWorkbench.vue
+++ b/apps/cloud/app/components/CloudMediaWorkbench.vue
@@ -1,4 +1,5 @@
<script setup lang="ts">
+import { STORAGE_CONNECTION_MESSAGES } from '@chronoframe/contracts/storage-diagnostics'
import type { Photo } from '@chronoframe/contracts/resources'
const api = $fetch as <T = unknown>(
path: string,
@@ -99,14 +100,22 @@ async function action(run: () => Promise<unknown>, success: string) {
} catch (error) {
failed.value = true
const code = (error as { statusCode?: number }).statusCode
+ const diagnostic = (error as { data?: { data?: { code?: string } } }).data
+ ?.data?.code
message.value =
- code === 409
- ? 'This item changed. Refresh and try again.'
- : code === 429
- ? 'The preview resource limit has been reached.'
- : code === 403
- ? 'Administrator access is required.'
- : 'The operation failed. Check storage permissions and CORS, then retry.'
+ diagnostic && Object.hasOwn(STORAGE_CONNECTION_MESSAGES, diagnostic)
+ ? STORAGE_CONNECTION_MESSAGES[
+ diagnostic as keyof typeof STORAGE_CONNECTION_MESSAGES
+ ]
+ : code === 503
+ ? 'Media services need deployment configuration. Check the selected environment settings.'
+ : code === 409
+ ? 'This item changed. Refresh and try again.'
+ : code === 429
+ ? 'The preview resource limit has been reached.'
+ : code === 403
+ ? 'Administrator access is required.'
+ : 'The operation failed. Check storage permissions and CORS, then retry.'
} finally {
busy.value = false
}
diff --git a/apps/cloud/server/utils/cloud-media.ts b/apps/cloud/server/utils/cloud-media.ts
index b6f9a30c..10e7b9ab 100644
--- a/apps/cloud/server/utils/cloud-media.ts
+++ b/apps/cloud/server/utils/cloud-media.ts
@@ -1,3 +1,7 @@
+import {
+ probeStorageConnection,
+ StorageConnectionError,
+} from '@chronoframe/storage/connection-probe'
import { createError, getRouterParam } from 'h3'
import type { H3Event } from 'h3'
import {
@@ -98,38 +102,12 @@ export async function checkStorage(
origin: string,
allowedHosts: string[],
) {
- validateCloudS3(config, allowedHosts)
- const s3 = createCloudS3(config, { allowedHosts }),
- key = 'chronoframe/connection-check/' + crypto.randomUUID()
- const sample = crypto.getRandomValues(new Uint8Array(32))
- let written = false
+ let s3: ReturnType<typeof createCloudS3>
try {
- await s3.put(key, sample, 'application/octet-stream')
- written = true
- const head = await s3.head(key),
- bytes = await s3.getProbe(key)
- if (
- head.bytes !== sample.length ||
- !bytes ||
- bytes.some((v, i) => v !== sample[i])
- )
- throw new Error('Storage read/write check failed')
- // Probe the presigned path too; raw responses and URLs are never returned/logged.
- const response = await fetch(await s3.signGet(key), {
- redirect: 'manual',
- signal: AbortSignal.timeout(15000),
- })
- if (!response.ok) throw new Error('Storage signed access failed')
- await response.body?.cancel()
- const multipartId = await s3.multipart(key, 'application/octet-stream')
- try {
- if (!(await s3.recoverMultipart(key)).includes(multipartId))
- throw new Error('Multipart recovery check failed')
- } finally {
- await s3.abort(key, multipartId)
- }
- if (!(await s3.cors(origin))) throw new Error('Storage CORS check failed')
- } finally {
- if (written) await s3.remove(key)
+ validateCloudS3(config, allowedHosts)
+ s3 = createCloudS3(config, { allowedHosts })
+ } catch {
+ throw new StorageConnectionError('configuration')
}
+ await probeStorageConnection(s3, origin)
}
diff --git a/apps/shared/platform/runtime.ts b/apps/shared/platform/runtime.ts
index 682b387d..e644fdfb 100644
--- a/apps/shared/platform/runtime.ts
+++ b/apps/shared/platform/runtime.ts
@@ -1,3 +1,4 @@
+import { StorageConnectionError } from '@chronoframe/storage/connection-probe'
import {
createError,
defineEventHandler,
@@ -77,6 +78,18 @@ export function definePlatformHandler<T>(
try {
return await handler(event)
} catch (error) {
+ if (error instanceof StorageConnectionError) {
+ setResponseHeader(event, 'Cache-Control', 'no-store')
+ return sendError(
+ event,
+ createError({
+ statusCode: 502,
+ statusMessage: 'Storage connection check failed',
+ data: { code: error.code },
+ }),
+ false,
+ )
+ }
const code = (error as { statusCode?: number })?.statusCode
const messages: Record<number, string> = {
400: 'Invalid request',
diff --git a/packages/contracts/package.json b/packages/contracts/package.json
index 046a9735..365bc230 100644
--- a/packages/contracts/package.json
+++ b/packages/contracts/package.json
@@ -13,7 +13,8 @@
"./settings": "./src/settings.ts",
"./social-links": "./src/social-links.ts",
"./queue": "./src/queue.ts",
- "./entry": "./src/entry.ts"
+ "./entry": "./src/entry.ts",
+ "./storage-diagnostics": "./src/storage-diagnostics.ts"
},
"scripts": {
"type-check": "tsc --noEmit"
diff --git a/packages/contracts/src/storage-diagnostics.ts b/packages/contracts/src/storage-diagnostics.ts
new file mode 100644
index 00000000..c279a8b8
--- /dev/null
+++ b/packages/contracts/src/storage-diagnostics.ts
@@ -0,0 +1,19 @@
+/** Public, fixed connection diagnostics; never expose provider responses or signed URLs. */
+export const STORAGE_CONNECTION_MESSAGES = {
+ storage_configuration_failed:
+ 'Check the S3 endpoint, region, bucket name and credential fields.',
+ storage_write_failed:
+ 'Storage write check failed. Check credentials, object-write permission and service availability.',
+ storage_read_failed:
+ 'Storage read check failed. Check object-read permission and service availability.',
+ storage_signed_read_failed:
+ 'Signed storage access failed. Check the endpoint, region and S3 credentials.',
+ storage_multipart_failed:
+ 'Multipart upload check failed. Check multipart creation, listing and abort permissions.',
+ storage_cors_failed:
+ 'Storage CORS check failed. Allow this portal origin, GET/PUT/HEAD, Content-Type, and expose ETag.',
+ storage_cleanup_failed:
+ 'Storage cleanup check failed. Check object-delete permission.',
+} as const
+export type StorageConnectionErrorCode =
+ keyof typeof STORAGE_CONNECTION_MESSAGES
diff --git a/packages/storage/package.json b/packages/storage/package.json
index d6a595b5..eb278e2a 100644
--- a/packages/storage/package.json
+++ b/packages/storage/package.json
@@ -14,7 +14,8 @@
"types": "./src/s3-edge.ts",
"default": "./dist/s3-edge.mjs"
},
- "./credential-cipher": "./src/credential-cipher.ts"
+ "./credential-cipher": "./src/credential-cipher.ts",
+ "./connection-probe": "./src/connection-probe.ts"
},
"scripts": {
"type-check": "tsc --noEmit",
diff --git a/packages/storage/src/connection-probe.ts b/packages/storage/src/connection-probe.ts
new file mode 100644
index 00000000..fe253272
--- /dev/null
+++ b/packages/storage/src/connection-probe.ts
@@ -0,0 +1,85 @@
+import type { StorageConnectionErrorCode } from '@chronoframe/contracts/storage-diagnostics'
+export type StorageProbeStage =
+ | 'configuration'
+ | 'write'
+ | 'read'
+ | 'signed_read'
+ | 'multipart'
+ | 'cors'
+ | 'cleanup'
+export class StorageConnectionError extends Error {
+ readonly code: StorageConnectionErrorCode
+ readonly stage: StorageProbeStage
+ constructor(stage: StorageProbeStage) {
+ super('Storage connection check failed')
+ this.name = 'StorageConnectionError'
+ this.stage = stage
+ this.code = `storage_${stage}_failed`
+ }
+}
+export interface StorageProbeClient {
+ put(key: string, body: Uint8Array, contentType: string): Promise<unknown>
+ head(key: string): Promise<{ bytes: number }>
+ getProbe(key: string): Promise<Uint8Array | undefined>
+ signGet(key: string): Promise<string>
+ multipart(key: string, contentType: string): Promise<string>
+ recoverMultipart(key: string): Promise<string[]>
+ abort(key: string, uploadId: string): Promise<unknown>
+ browserCors(origin: string, key: string): Promise<boolean>
+ remove(key: string): Promise<unknown>
+}
+/** Check only object-scoped operations. Provider errors are replaced with fixed codes. */
+export async function probeStorageConnection(
+ s3: StorageProbeClient,
+ origin: string,
+ request: typeof fetch = fetch,
+) {
+ const key = 'chronoframe/connection-check/' + crypto.randomUUID()
+ const sample = crypto.getRandomValues(new Uint8Array(32))
+ let stage: StorageProbeStage = 'write',
+ failure: StorageConnectionError | undefined
+ try {
+ await s3.put(key, sample, 'application/octet-stream')
+ stage = 'read'
+ const head = await s3.head(key),
+ bytes = await s3.getProbe(key)
+ if (
+ head.bytes !== sample.length ||
+ !bytes ||
+ bytes.length !== sample.length ||
+ bytes.some((v, i) => v !== sample[i])
+ )
+ throw new Error('Probe mismatch')
+ stage = 'signed_read'
+ const response = await request(await s3.signGet(key), {
+ redirect: 'manual',
+ signal: AbortSignal.timeout(15000),
+ })
+ try {
+ if (!response.ok) throw new Error('Signed access failed')
+ } finally {
+ await response.body?.cancel().catch(() => undefined)
+ }
+ stage = 'multipart'
+ const id = await s3.multipart(key, 'application/octet-stream')
+ try {
+ if (!(await s3.recoverMultipart(key)).includes(id))
+ throw new Error('Multipart recovery failed')
+ } finally {
+ await s3.abort(key, id)
+ }
+ stage = 'cors'
+ if (!(await s3.browserCors(origin, key)))
+ throw new Error('Browser CORS failed')
+ } catch {
+ failure = new StorageConnectionError(stage)
+ } finally {
+ // The PUT may have succeeded even when its response was lost.
+ try {
+ await s3.remove(key)
+ } catch {
+ failure ??= new StorageConnectionError('cleanup')
+ }
+ }
+ if (failure) throw failure
+}
diff --git a/packages/storage/src/s3-edge.ts b/packages/storage/src/s3-edge.ts
index 98c9dc82..c85eabbf 100644
--- a/packages/storage/src/s3-edge.ts
+++ b/packages/storage/src/s3-edge.ts
@@ -191,6 +191,89 @@ export function createCloudS3(
}
return bytes.subarray(0, size)
},
+ /** Verify browser behavior without reading administrative bucket configuration. */
+ async browserCors(origin: string, key: string) {
+ const putUrl = await getSignedUrl(
+ client,
+ new PutObjectCommand({
+ Bucket,
+ Key: safeKey(key),
+ ContentLength: 32,
+ ContentType: 'application/octet-stream',
+ }),
+ { expiresIn: 60 },
+ )
+ const getUrl = await getSignedUrl(
+ client,
+ new GetObjectCommand({ Bucket, Key: safeKey(key) }),
+ { expiresIn: 60 },
+ )
+ const headUrl = await getSignedUrl(
+ client,
+ new HeadObjectCommand({ Bucket, Key: safeKey(key) }),
+ { expiresIn: 60 },
+ )
+ const allowsOrigin = (r: Response) =>
+ [origin, '*'].includes(
+ r.headers.get('access-control-allow-origin') ?? '',
+ )
+ const values = (r: Response, h: string) =>
+ (r.headers.get(h) ?? '').split(',').map((v) => v.trim().toLowerCase())
+ for (const [method, url] of [
+ ['PUT', putUrl],
+ ['GET', getUrl],
+ ['HEAD', headUrl],
+ ] as const) {
+ const response = await transport(url, {
+ method: 'OPTIONS',
+ headers: {
+ Origin: origin,
+ 'Access-Control-Request-Method': method,
+ ...(method === 'PUT'
+ ? { 'Access-Control-Request-Headers': 'content-type' }
+ : {}),
+ },
+ redirect: 'manual',
+ signal: AbortSignal.timeout(15000),
+ })
+ try {
+ if (
+ !response.ok ||
+ !allowsOrigin(response) ||
+ !values(response, 'access-control-allow-methods').some(
+ (v) => v === method.toLowerCase() || v === '*',
+ )
+ )
+ return false
+ if (
+ method === 'PUT' &&
+ !values(response, 'access-control-allow-headers').some(
+ (v) => v === 'content-type' || v === '*',
+ )
+ )
+ return false
+ } finally {
+ await response.body?.cancel().catch(() => undefined)
+ }
+ }
+ const response = await transport(getUrl, {
+ headers: { Origin: origin },
+ redirect: 'manual',
+ signal: AbortSignal.timeout(15000),
+ })
+ try {
+ return (
+ response.ok &&
+ allowsOrigin(response) &&
+ response.headers.has('etag') &&
+ values(response, 'access-control-expose-headers').some(
+ (v) => v === 'etag' || v === '*',
+ )
+ )
+ } finally {
+ await response.body?.cancel().catch(() => undefined)
+ }
+ },
async cors(origin: string) {
const r = await client.send(new GetBucketCorsCommand({ Bucket }))
return (r.CORSRules ?? []).some(
diff --git a/scripts/check-entry-boundaries.mjs b/scripts/check-entry-boundaries.mjs
index 2073959f..36c857da 100644
--- a/scripts/check-entry-boundaries.mjs
+++ b/scripts/check-entry-boundaries.mjs
@@ -46,6 +46,7 @@ for (const entry of ['cloud', 'site']) {
'@chronoframe/database/cloud-resources',
'@chronoframe/storage/s3-edge',
'@chronoframe/storage/credential-cipher',
+ '@chronoframe/storage/connection-probe',
].includes(specifier)
if (
!edgeSafe &&
diff --git a/tests/cloud-storage-probe.test.ts b/tests/cloud-storage-probe.test.ts
new file mode 100644
index 00000000..19fddd7a
--- /dev/null
+++ b/tests/cloud-storage-probe.test.ts
@@ -0,0 +1,189 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import {
+ probeStorageConnection,
+ StorageConnectionError,
+ type StorageProbeClient,
+} from '../packages/storage/src/connection-probe.ts'
+import { createCloudS3 } from '../packages/storage/src/s3-edge.ts'
+function fixture(fail?: string) {
+ const calls: string[] = []
+ let data = new Uint8Array(0)
+ const hit = (stage: string) => {
+ calls.push(stage)
+ if (stage === fail)
+ throw new Error('provider-secret-and-signed-url-must-not-leak')
+ }
+ const client: StorageProbeClient = {
+ async put(key, bytes) {
+ assert.match(key, /^chronoframe\/connection-check\/[a-f0-9-]+$/)
+ data = bytes
+ hit('write')
+ },
+ async head() {
+ hit('read')
+ return { bytes: data.length }
+ },
+ async getProbe() {
+ return data
+ },
+ async signGet() {
+ hit('signed_read')
+ return 'https://private.example/object?secret=not-public'
+ },
+ async multipart() {
+ hit('multipart')
+ return 'upload-id'
+ },
+ async recoverMultipart() {
+ hit('recover')
+ return ['upload-id']
+ },
+ async abort() {
+ hit('abort')
+ },
+ async browserCors() {
+ hit('cors')
+ return true
+ },
+ async remove() {
+ hit('cleanup')
+ },
+ }
+ return { client, calls }
+}
+test('Connection probe checks object operations and returns only safe fixed failure codes', async () => {
+ for (const stage of [
+ 'write',
+ 'read',
+ 'signed_read',
+ 'multipart',
+ 'cors',
+ 'cleanup',
+ ]) {
+ const f = fixture(stage)
+ await assert.rejects(
+ probeStorageConnection(
+ f.client,
+ 'https://portal.example',
+ async () => new Response('ok'),
+ ),
+ (error) => {
+ assert(error instanceof StorageConnectionError)
+ assert.equal(error.code, 'storage_' + stage + '_failed')
+ assert(!JSON.stringify(error).includes('secret'))
+ assert(!error.message.includes('private.example'))
+ return true
+ },
+ )
+ assert(f.calls.includes('cleanup'))
+ }
+ const f = fixture()
+ await probeStorageConnection(
+ f.client,
+ 'https://portal.example',
+ async () => new Response('ok'),
+ )
+ assert.deepEqual(f.calls, [
+ 'write',
+ 'read',
+ 'signed_read',
+ 'multipart',
+ 'recover',
+ 'abort',
+ 'cors',
+ 'cleanup',
+ ])
+})
+test('Probe detects truncated content and preserves the primary error when compensation fails', async () => {
+ const short = fixture()
+ short.client.getProbe = async () => new Uint8Array(31)
+ await assert.rejects(
+ probeStorageConnection(short.client, 'https://portal.example'),
+ { code: 'storage_read_failed' },
+ )
+ const broken = fixture('recover')
+ broken.client.remove = async () => {
+ throw new Error('cleanup-secret')
+ }
+ await assert.rejects(
+ probeStorageConnection(
+ broken.client,
+ 'https://portal.example',
+ async () => new Response('ok'),
+ ),
+ { code: 'storage_multipart_failed' },
+ )
+ assert(broken.calls.includes('abort'))
+ const redirect = fixture()
+ await assert.rejects(
+ probeStorageConnection(
+ redirect.client,
+ 'https://portal.example',
+ async (_url, init) => {
+ assert.equal(init?.redirect, 'manual')
+ return new Response(null, { status: 302 })
+ },
+ ),
+ { code: 'storage_signed_read_failed' },
+ )
+})
+const config = {
+ endpoint: 'https://s3.us-east-1.amazonaws.com',
+ region: 'us-east-1',
+ bucket: 'private-bucket',
+ accessKeyId: 'test-access',
+ secretAccessKey: 'test-secret',
+}
+test('Browser CORS checks do not require GetBucketCors or bucket administration', async () => {
+ for (const failure of [
+ '',
+ 'origin',
+ 'method',
+ 'header',
+ 'etag',
+ 'redirect',
+ ]) {
+ const methods: string[] = []
+ const client = createCloudS3(config, {
+ fetch: async (input, init) => {
+ const url = new URL(
+ input instanceof Request ? input.url : String(input),
+ )
+ assert(!url.searchParams.has('cors'))
+ assert.equal(init?.redirect, 'manual')
+ methods.push(init?.method ?? 'GET')
+ if (failure === 'redirect')
+ return new Response(null, {
+ status: 302,
+ headers: { location: 'https://internal.invalid' },
+ })
+ const headers: Record<string, string> = {
+ 'access-control-allow-origin':
+ failure === 'origin'
+ ? 'https://other.example'
+ : 'https://portal.example',
+ 'access-control-allow-methods':
+ failure === 'method' ? 'GET' : 'GET, PUT, HEAD',
+ 'access-control-allow-headers':
+ failure === 'header' ? 'X-Other' : 'Content-Type',
+ 'access-control-expose-headers': failure === 'etag' ? 'Date' : 'ETag',
+ etag: 'probe-etag',
+ }
+ return new Response(init?.method === 'OPTIONS' ? null : 'probe', {
+ status: init?.method === 'OPTIONS' ? 204 : 200,
+ headers,
+ })
+ },
+ })
+ assert.equal(
+ await client.browserCors(
+ 'https://portal.example',
+ 'chronoframe/connection-check/test',
+ ),
+ !failure,
+ )
+ if (!failure)
+ assert.deepEqual(methods, ['OPTIONS', 'OPTIONS', 'OPTIONS', 'GET'])
+ }
+})