go-nc-exapp

Shared Go library for Nextcloud ExApp Services: AppAPI authentication, OCS JSON calls, per-user ExApp preferences, and an optional Required Groups Access Gate.

Import: gitea.neitzel.de/konrad/go-nc-exapp (package gonexapp).

Scope

Included

• Credentials — Nextcloud base URL, AppAPI secret, and requesting user identity
• AuthHeaders — outbound AppAPI authorization for OCS and other Nextcloud calls
• WithUser — credentials scoped to a specific requesting user
• UserFromRequest — extract the requesting user from inbound AppAPI-proxied requests
• OCSClient — authenticated OCS calls that always append format=json
• AppAPIPreferences — parameterized get/set of a string ExApp preference (caller supplies app id and key)
• Access Gate — optional Required Groups enforcement (Wrap + Check), English denied HTML for browsers, positive membership cache; env helpers for REQUIRED_GROUPS / REQUIRED_GROUPS_CACHE_SECONDS

Excluded

• ExApp lifecycle HTTP routes (/heartbeat, /enabled, …) — the Gate skips these by default but does not implement them
• HaRP listen / serve() and unix-socket bootstrap
• Top-menu, script, and iframe UI registration
• WebDAV and file storage (see go-nc-files)
• Visit folder resolution (see go-nc-files)

Usage

cred := gonexapp.Credentials{
    BaseURL:    "https://nextcloud.example",
    AppID:      "myexapp",
    AppVersion: "0.1.0",
    AAVersion:  "1.0.0",
    AppSecret:  os.Getenv("APP_SECRET"),
    UserID:     "alice",
}

prefs := gonexapp.NewAppAPIPreferences(cred, "myexapp", "savedDefault")
value, err := prefs.Get()

groupsEnv, groupsSet := os.LookupEnv("REQUIRED_GROUPS")
groups := gonexapp.ResolveRequiredGroups(groupsEnv, groupsSet, nil)
ttl := gonexapp.ParseCacheSeconds(os.Getenv("REQUIRED_GROUPS_CACHE_SECONDS"), gonexapp.DefaultCacheSeconds)
handler := gonexapp.AccessGate{Cred: cred, Groups: groups, CacheTTL: ttl}.Wrap(inner)

Each ExApp chooses its own preference keys; this library does not hardcode product-specific names.

Declare REQUIRED_GROUPS and REQUIRED_GROUPS_CACHE_SECONDS in the ExApp info.xml so Deploy options can set them.

Runnable package examples: go test -run Example.

Domain language

See CONTEXT.md for AppAPI credentials, Requesting user, ExApp preference, OCS, Required Groups, and Access Gate terminology.

Testing

Unit tests use httptest fake OCS servers. No live Nextcloud is required for Library CI.

Related

• go-nc-files — WebDAV, Working Folder, Saved Default, Visit resolution
• Workspace ADR 0013 — extraction from CheckDNS
• Workspace ADR docs/adr/go-nc-exapp/0001-required-groups-access-gate.md — Access Gate decisions