67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```go
|
|
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](./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
|