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.

docs: describe entry context and visitor authorization boundaries

HoshinoSuzumiBot57db836051ad
diff --git a/apps/platform-context.ts b/apps/platform-context.ts
index 5b3f1547..20e16b6c 100644
--- a/apps/platform-context.ts
+++ b/apps/platform-context.ts
@@ -19,6 +19,7 @@ import {
import { createError, getRouterParam } from 'h3'
import type { H3Event } from 'h3'
+/** Resolve the route Site through the portal session and its live Membership. */
export async function portalSiteContext(
event: H3Event,
config: { portalOrigin: string; secret: string },
@@ -30,11 +31,13 @@ export async function portalSiteContext(
'read',
)
}
+/** Resolve only published, verified mappings for the original Worker request Host. */
export async function publicSiteContext(event: H3Event) {
return platformAccess(event).resolvePublicSite(
platformRequestURL(event).hostname,
)
}
+/** Project a scoped UI context; public responses exclude Workspace and member details. */
export async function siteContextDTO(
event: H3Event,
context: PortalContext | PublicSiteContext,
@@ -54,6 +57,7 @@ export async function siteContextDTO(
: {}),
}
}
+/** Require an unexpired platform session on the configured portal origin. */
export async function requirePlatformSession(
event: H3Event,
config: { portalOrigin: string; secret: string },
diff --git a/apps/platform-crypto.ts b/apps/platform-crypto.ts
index 9c972cea..e232cbe9 100644
--- a/apps/platform-crypto.ts
+++ b/apps/platform-crypto.ts
@@ -36,6 +36,7 @@ export async function createEmailCodeCrypto(
// Conservative cost for Workers deployments that enforce the Web Crypto PBKDF2 cap.
export const VISITOR_PBKDF2_ITERATIONS = 100_000
+/** Derive a portable PBKDF2-SHA256 verifier; callers must use a unique salt per policy. */
export async function visitorPasswordHash(
password: string,
salt: string,
diff --git a/apps/platform-visitor.ts b/apps/platform-visitor.ts
index b9c5e34e..c9fd40e1 100644
--- a/apps/platform-visitor.ts
+++ b/apps/platform-visitor.ts
@@ -15,6 +15,7 @@ export { visitorPasswordHash } from './platform-crypto.ts'
const encoder = new TextEncoder()
const COOKIE = '__Host-chronoframe-visitor'
const TTL = 60 * 60 * 1000
+/** Import the independent visitor MAC key, rejecting unconfigured deployments. */
async function signingKey(secret: string) {
if (encoder.encode(secret).length < 32) throw createError({ statusCode: 503 })
return crypto.subtle.importKey(
@@ -25,6 +26,7 @@ async function signingKey(secret: string) {
['sign', 'verify'],
)
}
+/** Sign Host-bound Site/album grants without carrying any platform identity. */
export async function encodeVisitorGrants(
secret: string,
host: string,
@@ -40,6 +42,7 @@ export async function encodeVisitorGrants(
)
return body + '.' + btoa(String.fromCharCode(...new Uint8Array(signature)))
}
+/** Verify the Host MAC and retain well-formed grants with bounded, unexpired lifetimes. */
export async function decodeVisitorGrants(
secret: string,
host: string,
@@ -78,6 +81,7 @@ export async function decodeVisitorGrants(
return []
}
}
+/** Load this Site's album policy, rejecting absent or malformed verifier records. */
async function policy(
event: H3Event,
context: PublicSiteContext,
@@ -102,6 +106,7 @@ async function policy(
throw createError({ statusCode: 503 })
return result
}
+/** Check the current password revision against visitor grants, never platform cookies. */
export async function visitorAccess(
event: H3Event,
context: PublicSiteContext,
@@ -119,6 +124,7 @@ export async function visitorAccess(
unlocked: hasSiteVisitorGrant(context, grants, albumId, current.revision),
}
}
+/** Verify a same-origin, rate-limited password attempt and issue a scoped visitor grant. */
export async function unlockVisitor(
event: H3Event,
context: PublicSiteContext,
diff --git a/packages/console/app/composables/useConsoleApi.ts b/packages/console/app/composables/useConsoleApi.ts
index b937552e..1de8c01c 100644
--- a/packages/console/app/composables/useConsoleApi.ts
+++ b/packages/console/app/composables/useConsoleApi.ts
@@ -1,7 +1,9 @@
import { useEntryApi, useEntryFetch } from '#gallery/composables/useEntryApi'
+/** Create a console transport bound to the current Site/account and entry API origin. */
export function useConsoleApi() {
return useEntryApi(useRuntimeConfig().public.console.apiBase)
}
+/** Preserve useFetch response inference while applying console transport and scope keys. */
export const useConsoleFetch = ((
request: unknown,
options?: Record<string, unknown>,
diff --git a/packages/contracts/src/entry.ts b/packages/contracts/src/entry.ts
index a3fd584f..551fc267 100644
--- a/packages/contracts/src/entry.ts
+++ b/packages/contracts/src/entry.ts
@@ -46,6 +46,7 @@ export interface EntrySiteContext {
capabilities: EntryCapabilities
}
+/** Prefix resolved Site APIs and reject traversal; preserve legacy Self-hosted paths. */
export function entryRequestPath(
path: string,
context: EntrySiteContext | null,
diff --git a/packages/gallery/app/composables/useEntryApi.ts b/packages/gallery/app/composables/useEntryApi.ts
index c1beccfe..db60680c 100644
--- a/packages/gallery/app/composables/useEntryApi.ts
+++ b/packages/gallery/app/composables/useEntryApi.ts
@@ -10,6 +10,7 @@ export function useEntryApi(baseURL: string) {
return fetcher(entryRequestPath(request, snapshot), { ...options, baseURL })
}) as typeof $fetch
}
+/** Keep reactive fetch paths and hydration-cache keys inside the active entry scope. */
export function useEntryFetch(
request: unknown,
options: Record<string, unknown> | undefined,
diff --git a/packages/gallery/app/composables/useEntryContext.ts b/packages/gallery/app/composables/useEntryContext.ts
index e2e6d2e8..cf1781a9 100644
--- a/packages/gallery/app/composables/useEntryContext.ts
+++ b/packages/gallery/app/composables/useEntryContext.ts
@@ -8,6 +8,7 @@ import { SELF_HOSTED_CAPABILITIES } from '@chronoframe/contracts/entry'
export function useEntryContext() {
return useState<EntrySiteContext | null>('entry-site-context', () => null)
}
+/** Prefer server-resolved Site capabilities, with the entry profile as the bootstrap default. */
export function useEntryCapabilities(): EntryCapabilities {
return (
useEntryContext().value?.capabilities ??
diff --git a/packages/gallery/app/composables/useGalleryApi.ts b/packages/gallery/app/composables/useGalleryApi.ts
index 50392cc7..985bc0ae 100644
--- a/packages/gallery/app/composables/useGalleryApi.ts
+++ b/packages/gallery/app/composables/useGalleryApi.ts
@@ -1,7 +1,9 @@
import { useEntryApi, useEntryFetch } from './useEntryApi'
+/** Create a request-scoped gallery transport using this entry's API origin. */
export function useGalleryApi() {
return useEntryApi(useRuntimeConfig().public.gallery.apiBase)
}
+/** Preserve useFetch response inference while applying gallery transport and scope keys. */
export const useGalleryFetch = ((
request: unknown,
options?: Record<string, unknown>,
diff --git a/packages/gallery/app/composables/useImageLoader.ts b/packages/gallery/app/composables/useImageLoader.ts
index 6970bd8b..fd208c86 100644
--- a/packages/gallery/app/composables/useImageLoader.ts
+++ b/packages/gallery/app/composables/useImageLoader.ts
@@ -1,6 +1,7 @@
import type { LoadingIndicatorRef } from '#gallery/components/photo/LoadingIndicator.vue'
import { ImageLoaderManager } from '#gallery/libs/image-loader-manager'
+/** Manage the current image load with cleanup and a snapshot of the entry scope. */
export const useImageLoader = (
src: string,
isCurrentImage: boolean,
diff --git a/packages/gallery/app/libs/image-loader-manager.ts b/packages/gallery/app/libs/image-loader-manager.ts
index e52d0a1b..13d4ccc2 100644
--- a/packages/gallery/app/libs/image-loader-manager.ts
+++ b/packages/gallery/app/libs/image-loader-manager.ts
@@ -41,12 +41,14 @@ const normalImageCache: LRUCache<string, ImageLoaderCacheResult> = new LRUCache<
}
})
+/** Release cached object URLs when the client changes Site or principal. */
export function clearImageLoaderCache() {
normalImageCache.clear()
}
export class ImageLoaderManager {
private readonly scope: string
+ /** Bind image cache lookups to the creating entry scope. */
constructor(scope = 'self-hosted') {
this.scope = scope
}
@@ -154,6 +156,7 @@ export class ImageLoaderManager {
})
}
+ /** Reuse object URLs only within this loader's scope, caching new image blobs on misses. */
async processNormalImage(
blob: Blob,
originalUrl: string,
diff --git a/packages/platform/src/index.ts b/packages/platform/src/index.ts
index e7d0194f..0a1149d8 100644
--- a/packages/platform/src/index.ts
+++ b/packages/platform/src/index.ts
@@ -147,8 +147,10 @@ export interface PlatformSiteSummary {
published: boolean
role: 'admin' | 'member'
}
+/** Read portal Site metadata through live Workspace Memberships; never infer a default Site. */
export function createD1SiteCatalog(db: PlatformD1) {
return {
+ /** Return this user's readable Sites, including their unpublished drafts. */
async list(userId: number): Promise<PlatformSiteSummary[]> {
// JSON aggregation avoids exposing driver-specific `all()` result types.
const row = await db
@@ -168,6 +170,7 @@ export function createD1SiteCatalog(db: PlatformD1) {
> & { published: number })[]
).map((site) => ({ ...site, published: site.published === 1 }))
},
+ /** Read a name after the caller has independently authorized or resolved the Site. */
async name(siteId: number): Promise<string> {
const row = await db
.prepare('SELECT name FROM platform_sites WHERE id = ?')