Immich Photos

This composer Sprig signs in directly to a user-selected Immich instance, browses recent photos, and inserts either an Immich share link or a FILEHOST/upload-provider copy into Mango’s message draft. The user remains in control of the final IRC message.

It requires Mango 3.1 or newer and an Immich server with OAuth login enabled. The OAuth or OpenID Connect client configured at the identity provider used by Immich must allow mango://grove/oauth as an additional exact redirect URI. Keep Immich’s existing browser and mobile redirect URIs. This requirement applies to Authentik, Keycloak, Authelia, and any other provider that validates redirect URIs; the extension itself remains provider agnostic.

Sign-in flow

Immich brokers its configured login provider, so the extension needs no provider-specific code or configuration in Mango:

1. Mango creates a one-time state and S256 PKCE transaction through grove.oauth.prepare().
2. The extension sends the callback, state, and challenge to the selected Immich server’s /api/oauth/authorize endpoint.
3. Mango opens the authorization URL returned by Immich in an isolated system authentication session and validates the callback. The isolated session prevents an identity provider’s unrelated browser login from silently selecting the wrong Immich account.
4. The extension sends that callback and Mango’s verifier to /api/oauth/callback.
5. Immich returns its own access token, which is stored in grove.secrets.application (Keychain), never Web storage.

The extension does not know or configure any identity provider behind Immich. It receives no password.

Permissions

• oauth.authorize opens the user-visible system sign-in session.
• network.request makes bounded native HTTPS requests to Immich instances that do not permit browser CORS.
• storage.secure stores the Immich session in Mango’s Keychain namespace.
• uploads.use hands one bounded display-quality rendition to Mango’s configured native uploader without exposing its credentials to the extension.
• https://* lets users enter any self-hosted Immich origin and lets Mango open whatever HTTPS identity-provider URL that instance returns. This broad destination grant is visible in the installation consent sheet.

Native requests never follow redirects automatically and reject unsafe headers, non-HTTPS destinations, oversized request/response bodies, and destinations outside the accepted host permissions. Immich thumbnail redirects are accepted only when they stay on the selected instance and within the same asset path, then requested as a separately validated hop. Thumbnail requests are limited to four at a time.

Sharing behavior

The picker browses recent photos, favorites, and albums. Photo collections start with the newest 60 images and fetch older pages as the user scrolls; the Albums source shows cover art and drills into each album. Immich link creates one Immich INDIVIDUAL shared link with downloads enabled and metadata hidden; the user chooses a one-day, seven-day, 30-day, or non-expiring link. Uploaded copy downloads Immich’s display-quality preview and hands it to Mango’s configured native uploader, which avoids placing the Immich instance hostname in the draft. Mango inserts either resulting URL into the composer and never sends it automatically.

Test

node Examples/grove-immich-composer/immich-client.test.cjs