feat(web-app-ai-image-alt-text-sidebar): add AI Image Alt-Text Generator

[LukasHirt]

AI-generated · OSPO-46 · Gate: ✅ 1.00

Problem

Teams sharing images in oCIS have no way to generate descriptive alt text for accessibility or search-indexing purposes. Writing it manually is slow and routinely skipped, leaving images undiscoverable and inaccessible to screen readers.

Solution

Selecting any image file (.jpg, .png, .webp, .gif) reveals an "Alt Text" sidebar tab. The panel downloads the image via WebDAV, base64-encodes it, and sends it to a vision-capable LLM; the suggested alt text is shown in an editable field the user can copy. Tier 1 (vision model configured): full descriptive alt text generated. Tier 2 (text-only model): panel shows a one-line notice that the configured model does not support image input and prompts the admin to switch endpoints. No LLM configured: tab hidden entirely.

Extension points

global.files.sidebar (sidebarPanel) · global.files.context-actions (action)

Why ship this now

WCAG compliance is increasingly mandated in enterprise oCIS deployments, and this is the only extension in the set that addresses visual content via vision AI — a clearly distinct capability from the existing text-only AI extensions.

What was built

packages/web-app-ai-image-alt-text-sidebar — a new extension with two registration points (ai-image-alt-text.panel sidebar tab and ai-image-alt-text.action context-menu entry), both hidden entirely when no LLM is configured.

The sidebar panel (AltTextPanel.vue) covers all UI states: generating spinner, result textarea with Copy / Regenerate / Save buttons, a text-only-model notice, and an error banner. Generated alt text is persisted back to the file as the WebDAV custom property urn:oc:ai:alt-text:text via PROPFIND/PROPPATCH, so it survives panel close and re-open. A 4 MB image size guard is applied before the base64 payload is sent to the LLM.

The LLM composable (useLlm) introduces a three-state status — vision-ready / text-only / unconfigured — driven by a new optional vision: true flag on LlmConfig. The existing ai-doc-summary pattern is reused for the panel registration and config passthrough; the only new wiring is the image MIME-type guard and the multimodal payload.

Search-engine indexing of the stored WebDAV property requires a future server-side oCIS change and is out of scope here.

Gate

Check	Result
Hygiene	✅ ok
Build	✅ ok
Lint	✅ ok
Unit tests	✅ ok
Score	1.00

---

_{Effort: S · 🤖 Generated by extctl}

[kw-security]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[LukasHirt]

Converting to draft. There's a lot of issues that need to be taken care of before review.

[dj4oC]

Reviewed the web-app-ai-image-alt-text-sidebar draft. The structure is clean and i18n/ODS/test coverage is solid — notes below, ordered by severity. (Draft, so flagging rather than blocking.)

1. Security — oCIS access token sent to a configurable absolute endpoint

useAltText.ts attaches the oCIS access token as Authorization: Bearer on the request to ${cfg.endpoint}/chat/completions, where cfg.endpoint comes straight from applicationConfig.llm.endpoint. That's safe only while the endpoint is the same-origin ai-llm-proxy. If an admin points llm.endpoint directly at an external LLM (an easy misconfiguration), the user's oCIS access token is sent off-origin — CORS is not a confidentiality guarantee, and a permissive endpoint or a redirect can capture it.

Suggestion: only attach the Authorization header when the endpoint is same-origin (relative URL, or new URL(endpoint, location.origin).origin === location.origin), and/or document that llm.endpoint must be the proxy. ai-doc-summary / chat-with-file route through ai-llm-proxy; worth mirroring that contract here.

2. Correctness — panel does not react to resource changes

AltTextPanel.vue loads stored alt text only in onMounted, which fires once. oCIS reuses the sidebar-panel instance and just updates the resource prop on selection change (see chat-with-file's ChatPanel.vue, which watches () => props.resource?.id for exactly this reason). So switching from image A to image B does not reload B's stored alt text and leaves A's editableText displayed for B.

Suggestion: watch(resourceRef, ...) to reset editableText / altText / panelError and re-run loadStoredText on change.

3. Correctness — generate result can land on the wrong image

triggerGenerate() awaits a request with a 30s timeout, then assigns altText.value = result unconditionally. If the user switches files mid-generation, the result is applied to the now-selected image (same class as the load() race called out in #460). A monotonic token or aborting on resource change would close the window.

4. Type safety — props.resource as any

The panel casts props.resource as any when calling saveText / loadStoredText. The prop is typed AltTextResource (no webDavPath), but useAltTextStorage reads resource.webDavPath. It works at runtime only because index.ts passes a full Resource; the cast hides the mismatch. Typing the prop as Resource (or a shape that includes webDavPath) lets you drop the casts.

5. Minor

• useAltTextStorage.loadStoredText swallows all errors to storedText = null (a load failure looks like "no alt text") and shares the no-guard race from #2; degrades gracefully but worth a guard for consistency.
• No success feedback after Save (no toast); copyToClipboard silently no-ops when navigator.clipboard is unavailable.
• A 4 MB image inflates to ~5.3 MB base64 inline in the JSON body — combined with proxy/server body-size limits, very large allowed images could be rejected. The 4 MB cap is reasonable; just flagging the inflation.

Nice

Good $gettext/$pgettext coverage, ODS components throughout, the 4 MB guard, AbortSignal.timeout, status-code-based error mapping, and per-composable unit tests. Once #1–#3 are tightened this is in good shape.

[LukasHirt]

@dj4oC All points from your review have been addressed:

1. Security — buildHeaders now checks isSameOrigin(endpoint) before attaching the Authorization header; cross-origin endpoints never receive the oCIS access token.
2. Correctness (resource changes) — added a watch(() => props.resource?.id, ...) in the panel that resets state and reloads stored alt text on selection change.
3. Correctness (race condition) — triggerGenerate captures the resource id before the fetch and discards stale results/errors if the resource changed mid-flight.
4. Type safety — prop typed as Resource from @ownclouders/web-client; AltTextResource interface removed; all as any casts dropped.
5. Minor — loadError ref added to useAltTextStorage; save action shows a success toast; clipboard fallback shows an error toast instead of silently no-oping.

Unit tests added/updated for all of the above.

[dj4oC]

LGMT