# go-nc-exapp

Shared Go Library for Nextcloud ExApp Services: AppAPI authentication, OCS calls, per-user ExApp preferences, Notifications, Users and Groups, 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, preferences, and a Notification to that same user use this identity; there is no separate ExApp login.
_Avoid_: service account (for per-request identity), anonymous

**Recipient**:
The Nextcloud user a Notification is created for. May be the Requesting user or another user. AppAPI accepts one Recipient per call; sending to a group or to all admins is many Notifications.
_Avoid_: destination, target (HTTP), addressee, treating a group as a Recipient

**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

**Notification**:
A Nextcloud bell-icon message that an ExApp creates for one Recipient via AppAPI. It has a Subject, optional Message, optional Link, and optional rich-object params. AppAPI’s OCS is limited: no actions and no custom icon. One AppAPI call creates one Notification; the Recipient is the user the ExApp impersonates for that call, not a field in the message body.
_Avoid_: Denied UI, email, Talk message, in-app banner, toast, treating this as a full PHP INotifier

**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, Users and Groups (that is the OCS directory, not this ACL)

**Users and Groups**:
Nextcloud's Provisioning OCS this Library wraps as three reads: the groups of one user (as that user), the members of one group, and the instance group list. Member and instance lists run as the Requesting user and succeed only if that user is an admin or a subadmin of the group. Distinct from Required Groups.
_Avoid_: Group-API, Required Groups, AppAPI scopes, treating a group as a Recipient

**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). It reads the user's groups through Users and Groups. Lifecycle paths and top-menu script URLs under `/js/` stay ungated so Denied UI can load in the Nextcloud shell.
_Avoid_: Nextcloud middleware, HaRP ACL, admin bypass, gating the top-menu bootstrap script

**Top Menu visibility**:
Whether the ExApp app icon in the Nextcloud top menu is shown to all logged-in users or to Nextcloud admins only. Configured per deploy via env `TOP_MENU_ADMIN_REQUIRED` (`0` or `1`); the ExApp passes the value to AppAPI when registering the top-menu entry on enable. Independent of route `access_level` in info.xml and of Required Groups.
_Avoid_: route access_level, Required Groups, AppAPI group ACL