go-nc-exapp/CONTEXT.md

go-nc-exapp

Shared Go Library for Nextcloud ExApp Services: AppAPI authentication, OCS calls, per-user ExApp preferences, and optional Required Groups gating. ExApps import gitea.neitzel.de/konrad/go-nc-exapp. File storage and folder visits live in go-nc-files.

Language

AppAPI credentials: The ExApp's shared secret and Nextcloud base URL, plus optional per-request user identity. Used to sign outbound calls to Nextcloud and to read the requesting user from inbound AppAPI-proxied requests. Avoid: API key (generic), session token

Requesting user: The Nextcloud user on whose behalf the current ExApp request runs, taken from AppAPI authorization headers. WebDAV and preferences use this user; there is no separate ExApp login. Avoid: service account (for per-request identity), anonymous

ExApp preference: A string value stored in Nextcloud for one user and one ExApp, keyed by the ExApp (not admin AppConfig). Libraries expose a parameterized key; each ExApp chooses its own key names. Avoid: settings file in User Files, instance-wide config

OCS: Nextcloud's legacy HTTP API surface under /ocs/v2.php/…. This Library requests JSON responses (format=json) for machine-readable bodies. Avoid: assuming XML responses, REST-only Nextcloud APIs for ExApp prefs

Required Groups: The Nextcloud groups configured for an ExApp (comma-separated deploy env REQUIRED_GROUPS) such that membership in any one of them is enough to use the ExApp. Empty or unset means no group restriction. AppAPI does not enforce this; the ExApp does. Avoid: AppAPI scopes, route access_level, admin-only top menu, treating the ExApp id as an implicit group name

Access Gate: The Library check that enforces Required Groups for the Requesting user on ExApp HTTP traffic (403 or denied UI when not a member; 401 without a user; 503 when membership cannot be determined). Lifecycle paths stay ungated. Avoid: Nextcloud middleware, HaRP ACL, admin bypass