Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
fix(storage): support object-scoped connection probes
Timothy Yine088a63c00e3
diff --git a/apps/cloud/app/assets/cloud.css b/apps/cloud/app/assets/cloud.cssindex 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.vueindex 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 = trueconst code = (error as { statusCode?: number }).statusCode+ const diagnostic = (error as { data?: { data?: { code?: string } } }).data+ ?.data?.codemessage.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.tsindex 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.tsindex 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 })?.statusCodeconst messages: Record<number, string> = {400: 'Invalid request',diff --git a/packages/contracts/package.json b/packages/contracts/package.jsonindex 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.tsnew file mode 100644index 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_MESSAGESdiff --git a/packages/storage/package.json b/packages/storage/package.jsonindex 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.tsnew file mode 100644index 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.tsindex 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.mjsindex 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.tsnew file mode 100644index 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'])+ }+})