go-nc-exapp

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

Import: gitea.neitzel.de/konrad/go-nc-exapp

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, 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.

Domain language

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

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