# Quick 261009-dkv: Dateien Etappe 2a (Teilen) - Research

**Researched:** 2026-10-09
**Domain:** Nextcloud OCS Files Sharing API + Sharee API, integrated into the existing `nextcloud-files` module (NestJS + Next.js)
**Confidence:** HIGH (NC 34.0.4 server source read in the test container and probed live; write-path shapes from source, not from live POST/PUT)

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions
- Share targets: both. Colleagues (Nextcloud users AND groups, found via Nextcloud's sharee search) and public links.
- Link protection: follow the Nextcloud server policy, do not invent Tessera-side rules. User believes the company Nextcloud enforces a password for links but NOT an expiry date. Tessera must read the policy from the Nextcloud capabilities (password enforced, expiry enforced/default days, etc.) and reflect it in the form (required fields, defaults, maximums); Nextcloud's error messages on policy violations must be shown understandably in German. Optional fields (expiry when not enforced) remain freely settable.
- Permissions: simple choice "Ansehen" (read only) or "Bearbeiten" (edit). For folders additionally "Nur hochladen" (file drop / Briefkasten, mainly for public links). No per-bit checkboxes.
- Overview: both views "Von mir geteilt" and "Mit mir geteilt" as separate views in the module, plus a share indicator on every shared entry in the file list. Shares can be opened from both places to change or remove them.

### Claude's Discretion
Copy-link button, optional link label/note, notification behaviour (Nextcloud's own for user/group shares is fine), how "Mit mir geteilt" items are opened/navigated, accepting/declining pending incoming shares if the server requires it, UI layout of the share dialog (follow existing dialog patterns), error mapping, rate/size limits, test strategy.

### Deferred Ideas (OUT OF SCOPE)
Search (later quick). Not mentioned in CONTEXT but excluded by project memory: licensing, multi-tenancy topics.
</user_constraints>

## Project Constraints (from CLAUDE.md / memory)
- Work only via GSD workflow; German UI texts with "Sie", real umlauts; user chat in German with "du".
- Etappe-1 safety rules stay: fixed path prefixes (`/ocs/v2.php/` already allowed), no redirects, no cookies, never call a URL from an NC response, call gate on 429, German error contract (never 401/403 to the browser), `tenantId`/`userId` only from token.
- Every module change: module changelog entry + docs; no Docker deploy to the test server by Claude; no password-leak warnings; ASVS level 1, `security_enforcement: true`.

## Summary

The whole feature is a thin, typed proxy over eight OCS calls, all under the already allowed prefix `/ocs/v2.php/`. The existing `ocsRequest` (in `nextcloud-auth-client.ts`) is NOT usable as-is: it has no body/query support, it maps every 403 to `app-password-given` and throws away the body of every non-2xx answer, which is exactly where the share error messages live. Add a new share-specific OCS helper (in a new `nextcloud-shares.ts`, same layer as `nextcloud-dav.ts`) on top of `ncRequest` that returns `{status, ocsMessage, data}`.

Three server behaviours drive the design: (1) policy lives in `GET /ocs/v2.php/cloud/capabilities` and is PER USER (password-enforcement excludes groups); (2) on PUT, Nextcloud hides policy violations behind the generic message `Failed to update share.`, so Tessera must pre-validate password/expiry from the capabilities; (3) `createShare` has a Nextcloud user rate limit of 20 per 600 s, and a 429 without `Retry-After` would pause the ENTIRE origin for 15 min in Tessera's call gate, so Tessera needs its own lower per-user limit on creates.

**Primary recommendation:** New files `nextcloud-shares.ts` (OCS layer + parsers) and `nextcloud-files-shares.service.ts` (+ DTOs, controller routes), JSON bodies for POST/PUT, strict Tessera-side validation of date/permissions/recipient, capabilities fetched per request (short per-credential cache), password never stored/logged/echoed, 15-creates-per-10-min Tessera limiter, extend the unreleased module changelog entry 1.0.0.

## Architectural Responsibility Map

| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| Share CRUD, sharee search, capabilities | API / Backend (NestJS, own app password) | Nextcloud (authority) | Browser never talks to NC; credential is decrypted only in `getSession` |
| Policy enforcement (password/expiry/permissions) | Nextcloud | API pre-validation, Browser form hints | Server is authority; API/Browser only mirror it to avoid opaque errors |
| Share indicator in file list | API (parse `oc:share-types` from existing PROPFIND) | Browser | Data already requested by `PROPFIND_BODY`, just not parsed |
| Copy-link / display of link URL | Browser | API passes NC's `url` field | URL is only displayed/copied, never fetched by Tessera |
| Create-rate limiting | API (own limiter) | Nextcloud `UserRateLimit` | Avoid origin-wide gate pause |
| Sharee name resolution, "Mit mir geteilt" navigation | Browser (existing browser navigates `file_target`) | API | Received shares are mounted in the recipient's own tree |

## Standard Stack

No new packages. Everything needed exists: `undici` (via `ncRequest`), `class-validator` DTOs, vitest 3.2.6 (api) / 4.1.9 (web), Biome. **Package Legitimacy Audit:** not applicable, no external packages are installed in this task. Packages removed (SLOP): none. Flagged (SUS): none.

## Nextcloud API facts (all against NC 34.0.4 in `tessera-nc-test`)

All calls: `OCS-APIRequest: true`, `Accept: application/json` (already set by `ncRequest` with `ocs: true`), Basic auth with the user's app password. v2 mirrors the OCS status into the HTTP status. Body of POST/PUT may be JSON (`Content-Type: application/json`): [VERIFIED live: `POST {"path":"/nope","shareType":3}` returned `Wrong path, file/folder does not exist`, not `Please specify a file or folder path`, so the JSON body was parsed]. Use JSON bodies: password never appears in a URL and no form-encoding quirks.

### Endpoints [VERIFIED: /var/www/html/apps/files_sharing/appinfo/routes.php:83-125, ShareAPIController.php in container]
| Purpose | Call | Notes |
|---|---|---|
| List my shares | `GET /ocs/v2.php/apps/files_sharing/api/v1/shares` | No params = shares created by me (all types incl. email, talk, federated: filter client side to types you handle) |
| Shares of one path | `GET .../shares?path=/Projekte&reshares=true` | `path` relative to the user's home, same string as `entry.path`. Unknown path: HTTP 404 `Wrong path, file/folder does not exist`. Without resharing rights only own shares are returned |
| Shared with me | `GET .../shares?shared_with_me=true` | Own shares are filtered out. Types user, group (+circle, room, deck: ignore) |
| Pending incoming | `GET .../shares/pending` | Returns `permissions: 0` per item. Only relevant when the admin turned off auto-accept |
| Accept pending | `POST .../shares/pending/{id}` | Route exists for POST only (PUT gives 405). Decline = `DELETE .../shares/{id}` by the recipient |
| Create | `POST .../shares` | Body fields below |
| Update | `PUT .../shares/{id}` | Several fields in ONE request are fine (source handles permissions, password, expireDate, note, label together). If NONE of the known fields is sent: 400 `Wrong or no update parameter given`. Send only changed fields |
| Delete | `DELETE .../shares/{id}` | 200 with empty data. Recipient of a group share only leaves (deleteFromSelf) |
| Sharees | `GET .../sharees?search=&itemType=file\|folder&perPage=20&shareType%5B0%5D=0&shareType%5B1%5D=1` | `itemType` is REQUIRED (else 400 `Missing itemType`). `ncRequest.query` is a `Record<string,string>` so duplicate `shareType[]` is impossible; the indexed form `shareType[0]=0&shareType[1]=1` works [VERIFIED live, returned users+groups only] |
| Capabilities | `GET /ocs/v2.php/cloud/capabilities` | Per user. ~100 KB JSON |
| Password generate (optional) | `GET /ocs/v2.php/apps/password_policy/api/v1/generate` | Live answer `{"data":{"password":"YJMsw7P9DE"}}` (10 chars). Capabilities contain absolute `api.generate` URLs: ignore them, use the fixed path |

### Create body (POST) [VERIFIED: ShareAPIController::createShare signature]
`path` (string), `shareType` (0 user, 1 group, 3 link; 4 = email out of scope), `shareWith` (user id / group id; not for links), `permissions` (int), `password` (link), `expireDate` (`YYYY-MM-DD`), `label` (link, max 255), `note`, optional `sendMail` ('true'/'false').

Permission masks (read=1, update=2, create=4, delete=8, share=16):
| UI choice | Folder | File | Source of truth |
|---|---|---|---|
| Ansehen | 1 | 1 | |
| Bearbeiten | 15 (1+2+4+8) | 3 (1+2) | server strips create/delete for files: `$permissions & ~(Constants::PERMISSION_DELETE \| Constants::PERMISSION_CREATE)` |
| Nur hochladen (folder link only) | 4 | not offered | link validation: `Share must at least have READ or CREATE permissions` |
Do not send 16 (resharing) in this etappe. User/group shares always get READ OR-ed in by the server; send explicit permissions always (omitted = `default_permissions`, here 31 incl. share bit). Offer "Bearbeiten" only if the entry's DAV permission letters allow it (own root shows `RGDNVCK` [VERIFIED live PROPFIND]); letters: `R` reshare, `G` read, `W` write, `D` delete, `N`/`V` rename/move, `C`/`K` create, `S` = received share [ASSUMED: letter meaning from Nextcloud DAV docs, not re-read this session].

### Response share object [VERIFIED live for a user share; link-specific keys VERIFIED from formatShare source]
User share (live, folder `/Projekte` to `zoe`): `{"id":"1","share_type":0,"uid_owner":"anna","displayname_owner":"Anna Müller","permissions":31,"can_edit":true,"can_delete":true,"stime":1791532378,"parent":null,"expiration":"2026-12-31 23:59:59","token":null,"uid_file_owner":"anna","note":"","label":"","displayname_file_owner":"Anna Müller","path":"/Projekte","item_type":"folder","item_permissions":31,"is-mount-root":false,"mount-type":"","mimetype":"httpd/unix-directory","has_preview":false,"storage_id":"home::anna","storage":3,"item_source":294,"file_source":294,"file_parent":93,"file_target":"/Projekte","item_size":6810,"item_mtime":1791489905,"share_with":"zoe","share_with_displayname":"Zwei Faktor","share_with_displayname_unique":"zoe","mail_send":1,"hide_download":0,"attributes":null}` (data is an OBJECT for POST/PUT, an ARRAY for GET lists and GET by id).
Link shares additionally carry `token`, `url`, `password` (the literal string `redacted` when set, else null), `share_with` (same redacted value), `send_password_by_talk`. `expiration` is `Y-m-d H:i:s` in the server timezone: take the first 10 chars. For incoming shares `file_target` is the path inside the recipient's own tree and `item_permissions` are the effective permissions. Parse into a small Tessera `NcShare` type, never forward the raw object (drops `storage_id`, `attributes`, etc.).

### Capabilities (policy) [VERIFIED: Capabilities.php source + live JSON]
Live (`files_sharing`): `public.password.enforced=false`, `public.password.askForOptionalPassword=false`, `public.expire_date.enabled=false`, `public.expire_date_internal.enabled=false`, `public.upload=true`, `public.upload_files_drop=true`, `public.multiple_links=true`, `resharing=true`, `group_sharing=true`, `default_permissions=31`, `sharee.minSearchStringLength=0`, `sharebymail.password.enforced=false`.
Rules from the source you must reproduce:
- If link sharing is off: `public = {"enabled": false}` and NO other `public.*` keys. If the share API is off: `api_enabled=false`. Hide the whole Teilen feature then.
- `public.expire_date.{days,enforced}` exist ONLY when `public.expire_date.enabled` is true (enabled = default expiry configured). Same for `public.expire_date_internal` (applies to USER and GROUP shares, and it sits inside `public`, so it is missing when links are disabled: treat missing as "no policy").
- `public.password.enforced` is evaluated for the calling user (excluded groups: `shareapi_enforce_links_password_excluded_groups`): fetch with the user's own credential, never cache across users.
- `password_policy` capability exists (`minLength: 10`, `enforceNonCommonPassword: true`, HIBP true in the test server). Which context applies to sharing is unclear (only an `account` context is listed): use it as a hint only.
- Expiry semantics [VERIFIED: Manager::validateExpirationDateLink]: today is allowed, earlier is `Expiration date is in the past`; when enforced the date must be present and at most today + `days` (`Cannot set expiration date more than %n days in the future`). When a default expiry is enabled and NO `expireDate` is sent on create, the server fills today + default days. To create WITHOUT expiry when it is optional, send `expireDate: ""` (empty string sets `setNoExpirationDate`). So: pre-fill the form with today+days when `enabled`, send `""` when the user clears an optional field, omit it only to accept the server default.
- PHP parsing of `expireDate` is lenient: `"31.12.2026x"` was ACCEPTED and created a share [VERIFIED live, see Test-state note]. Tessera must validate `^\d{4}-\d{2}-\d{2}$` AND a real calendar date and send exactly that.

### Error shapes (OCS meta in the body; HTTP status mirrors `statuscode`) [VERIFIED live unless noted]
| Case | HTTP | `ocs.meta.message` |
|---|---|---|
| unknown path | 404 | `Wrong path, file/folder does not exist` |
| unknown share id (GET/PUT/DELETE/accept) | 404 | `Wrong share ID, share does not exist` |
| unknown user | 404 | `Please specify a valid account to share with` |
| unknown group | 404 | `Please specify a valid group` [source] |
| unknown share type | 400 | `Unknown share type` |
| bad link permissions (2) | 400 | `Share must at least have READ or CREATE permissions` |
| label > 255 | 400 | `Maximum label length is 255` |
| public upload on a file | 400 | `Public upload is only possible for publicly shared folders` |
| `sharees` without itemType | 400 | `Missing itemType` |
| password policy violated (POST and PUT) | 400 | the policy hint text, e.g. validate endpoint says `Password is among the 1,000,000 most common ones. Please make it unique. Password needs to be at least 10 characters long. Password is present in compromised password list. Please choose a different password.` [HintException wrapped as 400, source] |
| create: password missing while enforced, expiry rules, already-exists-via-group, sharing disabled, folder contains received shares | 403 | e.g. `Passwords are enforced for link and mail shares`, `Expiration date is enforced`, `You cannot share a folder that contains other shares` [source: `GenericShareException\|\InvalidArgumentException` become `OCSForbiddenException`] |
| update: ANY non-hint failure (enforced password removed, bad expiry, ...) | 400 | only `Failed to update share.` (details are logged server-side, not returned) |
| update of a share you did not create (recipient) | 403 | `You are not allowed to edit incoming shares` |
| delete without right | 403 | `Could not delete share` |
| user rate limit on create | 429 | no `Retry-After` header seen in the AppFramework code [VERIFIED: grep found none]; limit `#[UserRateLimit(limit: 20, period: 600)]` on `createShare` |
Messages are localized with the NC user's language, so never switch on message text. Map on (operation, HTTP status, whether password/expireDate were sent) and show the NC message as a secondary line (plain text, control chars stripped, max ~300 chars). Pre-validation from capabilities makes most of these unreachable.

Other verified behaviours:
- POST for a recipient that already has the share returns HTTP 200 with the EXISTING share, unchanged, and re-triggers the notification (`catch (AlreadySharedException $e) { ... $share = $e->getExistingShare();` in Manager::createShare). So the UI must not offer already-shared recipients and must use PUT to change permissions.
- Default notification: `mail_send` is 1 for user shares by default (mail goes out only if the recipient has an address and NC mail works). Leave Nextcloud's behaviour (decision: discretion), do not send `sendMail`.
- `sharees` result: `{"exact":{...},"users":[{"label":"Zwei Faktor","subline":"","icon":"icon-user","value":{"shareType":0,"shareWith":"zoe"},"shareWithDisplayNameUnique":"zoe","status":[]}],"groups":[{"label":"twofa","value":{"shareType":1,"shareWith":"twofa"}}],"remotes":[],"emails":[],...}`. Users and groups appear in `users`/`groups` AND (on exact match) in `exact.*`: merge and dedupe by `shareType:shareWith`. The caller (anna) is not listed. Pagination via `Link` response header (ignore, `perPage=20` is enough; the user refines the search).
- PROPFIND already requests `<oc:share-types/>`; unshared entries return an empty element (`<oc:share-types/>`, live). `parsePropfind` has `isArray` for `share-type` but `buildEntry` never reads it: add `shareTypes: number[]` to `NcEntry` (and to the web `NcEntry`). Received items carry the `S` letter in `oc:permissions` and are mounted at `file_target`.
- GET list responses are capped by `OCS_MAX_BYTES = 1 MiB` in `ocsRequest`; the new helper needs its own cap (suggest 8 MiB) and a share count cap (e.g. 2000, `truncated` flag like `MAX_LIST_ENTRIES`).

## Integration points (Etappe-1 code)

| Concern | Where | What to do |
|---|---|---|
| OCS transport | `apps/api/src/nextcloud-files/nextcloud-auth-client.ts` `ocsRequest` (lines ~120-175): `ncRequest(... prefix '/ocs/v2.php/', ocs: true)` | Do not extend it for shares (login code relies on 403 = `app-password-given`). Write `ocsShareRequest` in a new file using `ncRequest` with `method`, `segments` (e.g. `['apps','files_sharing','api','v1','shares', id]`), `query` (encoded per key/value by `buildNcUrl`), `headers: {'content-type':'application/json'}`, `body: JSON.stringify(...)`, `authorization/credentialKey` from `NcSession`. Return `{status, ocsMessage, data}`; read the body for non-2xx (cap 64 KiB) |
| Path whitelist | `nextcloud-http.ts` `ALLOWED_PREFIXES` | `/ocs/v2.php/` already allowed, nothing to add. `buildNcUrl` requires prefix ending in `/` for segments |
| Segments | `validateSegment` / `encodeSegments` | Share id: validate `^\d{1,20}$` in the DTO (`@Matches`) before it becomes a segment; entry `path` goes through `parseUserPath` and is rebuilt as `/${segments.join('/')}` before it is put in query/body |
| Session + errors | `NextcloudFilesService.session()/fail()` pattern, `mapNcFailure` in `nextcloud-upstream.ts` | New service uses `account.getSession(tenantId, userId)`, `mapNcFailure` for transport errors (401/credential-dead -> `connectionExpired`, paused/429 -> `nextcloudLocked`). Share-specific statuses go through a new mapper (below) |
| Error contract | `nextcloud-files.types.ts` `NcErrorCode` + `NC_ERROR_DEFAULTS` (never 401/403) | Add codes with German texts and HTTP 4xx other than 401/403: `shareRejected` (422, carries `ncMessage`), `sharePasswordRejected` (400, carries `ncMessage`), `shareExpiryInvalid` (400), `shareRecipientInvalid` (404 -> use 422 to avoid clashing with `notFound`), `shareLimit` (429 -> `tooManyAttempts`-style with `retryAfterSeconds`, own code `tooManyShares`), `sharingDisabled` (409). Web: add them to `KNOWN` in `components/nextcloud-files/error-text.ts` and to `nextcloudFiles.codes` in `src/messages/de.json`/`en.json` |
| Controller | `nextcloud-files.controller.ts` | Routes under `modules/nextcloud-files`. Static first, params at the END (spec `nextcloud-files.controller.spec.ts:193` checks order): `GET shares/capabilities`, `GET shares/mine`, `GET shares/received`, `GET shares/by-path`, `GET sharees`, `POST shares`, then at the end `PUT shares/:id`, `DELETE shares/:id`, `POST shares/:id/accept`. Class-level `@UseModule`, no role decorator (Benutzen level, like all file routes); update the doc comment listing routes |
| Rate limit | `nextcloud-login-guard.ts` has `pruneTimes` + `checkFlowStart` (10 per 10 min per user) | Add a sibling `checkShareCreate(userId)`: 15 per 10 min per user, throws `tooManyShares`. Reason: NC allows 20/600 s; its 429 has no `Retry-After`, `gate.pause(origin, undefined)` then pauses ALL users for `DEFAULT_PAUSE_SECONDS = 15 * 60` |
| Entry model | `nextcloud-propfind.ts` `NcEntry` (`permissions`, `fileId`, `favorite`...) | Add `shareTypes`; update `nextcloud-propfind.spec.ts`; web `lib/nextcloud-files-api.ts` `NcEntry` |
| Row menu | `FileBrowser.tsx` `menuActions(entry)` (lines ~638-695), `EntryAction` in `EntryMenu.tsx` | Insert `{id:'share', label, icon, onSelect: () => setDialog({kind:'share', entry})}` after `move`, only when `entry.permissions.includes('R')` (and multi-select: no share action, single entry only). Extend `DialogState` (line ~51) |
| Dialog | `components/Dialog.tsx` (`title`, `footer`, `wide`, `initialFocus`, focus trap, Escape) | `ShareDialog.tsx` wide variant; sections: "Mit Personen oder Gruppen" (sharee search + list), "Link" (create/list). Pattern of `NameDialog.tsx`/`DeleteDialog.tsx` for submit/error state; errors via `errorText(t, toErrorLike(err), locale)` |
| List indicator | `FileList.tsx`, `FileGrid.tsx`, `TypeTile.tsx` | Small share icon when `entry.shareTypes.length > 0` or permissions contain `S`; click opens the dialog; add an `aria-label`. After any share change re-list the folder |
| Views | `app/(portal)/modules/nextcloud-files/page.tsx` (`TabId = 'files' | 'settings'`, TabBar rendered only `canManage`) | Add `sharedByMe`, `sharedWithMe` to `TabId`; show the TabBar for every connected user (today it only renders for managers). New components `SharesView.tsx` (list, actions). "Mit mir geteilt" item click: switch to tab `files` and navigate `FileBrowser` to `file_target` (folder) or its parent (file) with the file preselected; needs a `initialPath` prop on `FileBrowser` |
| Module version | `nextcloud-files.changelog.ts` (only entry `1.0.0`, date `2026-10-08`), seed uses `latestVersion(...)` | Last tag `v1.10.1` (2026-10-06), `CHANGELOG.md` lists "Neues Modul Dateien" under "Unveröffentlicht", so the 1.0.0 entry is unreleased: per `docs/anleitung-entwicklung.md` ("Höchstens ein Sprung je Modul zwischen zwei Tessera-Freigaben") extend the 1.0.0 entry with `new` items (de+en, "Sie", real umlauts). `module-changelog.spec.ts:202` pins exactly one entry `1.0.0` / `2026-10-08`: leave as is. If the planner prefers 1.1.0, that test must change too |
| Docs | `docs/anleitung-anwender.md` section "Dateien (Nextcloud)" (menu sentence lists "Öffnen, Herunterladen, Umbenennen, Verschieben, „In Nextcloud öffnen“ und Löschen"), `docs/anleitung-administration.md` "Dateien: Nextcloud anbinden", `docs/anleitung-betrieb.md` "Dateien (Nextcloud)" + troubleshooting table, `docs/anleitung-entwicklung.md` (share layer, route list), root `CHANGELOG.md` "Unveröffentlicht" | Admin doc: the sharing rules (password, expiry, link upload) are set in Nextcloud Administration > Sharing and Tessera mirrors them. Betrieb: 20/10-min Nextcloud limit, Tessera limit 15, link URL host comes from Nextcloud's own address settings (`overwritehost`/trusted domain) |

## Architecture

```
Browser (ShareDialog / SharesView / list icon)
   | JSON, cookie auth
   v
Controller (UseModule, tenant+user from token) -> DTO validation (class-validator, strict date/permission enum)
   v
NextcloudFilesSharesService
   |-- shareCreateLimiter (per user)         -> 429 tooManyShares (no NC call)
   |-- getSession(tenantId,userId) -> NcSession (credentialKey, Basic auth)
   |-- pre-validate vs capabilities (password required, expiry window, link allowed, drop allowed)
   v
nextcloud-shares.ts  ocsShareRequest -> ncRequest (gate, no redirects, no cookies, 4 concurrent/key)
   v
Nextcloud /ocs/v2.php/apps/files_sharing/api/v1/...  (+ /cloud/capabilities)
   v
parsers -> NcShare / NcSharee / NcSharePolicy  -> JSON to browser (no password, no raw object)
```

Recommended new files: `nextcloud-shares.ts`, `nextcloud-shares.spec.ts`, `nextcloud-files-shares.service.ts` (+ `.spec.ts`), `dto/nextcloud-files-shares.dto.ts`; web `lib/nextcloud-files-api.ts` additions (+ test), `components/ShareDialog.tsx`, `SharesView.tsx`, `ShareIndicator`, `components/nextcloud-files/share-policy.ts` (pure functions: permission choice -> bitmask, min/max date, password required, with unit tests).

Patterns to follow:
- **Policy DTO to browser** `NcSharePolicy`: `{enabled, linksEnabled, linkPasswordRequired, linkExpiry:{enabled,days,enforced}, internalExpiry:{enabled,days,enforced}, uploadAllowed, dropAllowed, groupsEnabled, minSearchLength, passwordMinLength|null}`. The API re-checks the same rules on write (do not trust the browser), but only for rules it can know from capabilities.
- **Permission DTO**: accept `access: 'view' | 'edit' | 'upload'` plus the entry type from the server (the API itself looks up the type via `PROPFIND Depth 0` or trusts nothing: simplest is `GET shares?path=` is not enough; use `dav.list`-style `parsePropfindSelf` that exists) and compute the bitmask server-side. Never accept raw bitmasks from the browser.
- **Update**: compute the diff in the browser, send only changed fields; empty string semantics: `password:""` removes, `expireDate:""` removes, `label`/`note` `""` clear.
- **Display of the link**: show `share.url` only if it parses as http/https; render in a read-only input + "Link kopieren" via `navigator.clipboard`; Tessera never requests it.

## Don't Hand-Roll

| Problem | Don't build | Use instead | Why |
|---|---|---|---|
| Password rules | A Tessera password policy | NC capabilities hint + show NC's 400 message | Policy, HIBP and common-password lists live in NC |
| Expiry rules | Own default/maximum | `public.expire_date{,_internal}.{enabled,days,enforced}` | Admin-configurable per server |
| User/group lookup | Own directory query (LDAP) | Sharee API | NC applies its enumeration restrictions (`shareapi_restrict_user_enumeration_*`) |
| Random password | A custom generator | NC `password_policy/api/v1/generate`, fallback `crypto.getRandomValues` 20 chars | Server-compliant. (10-char output from NC today; fine) |
| Link URL | Building `/s/<token>` yourself | `url` field from the share | NC knows its public host |

## Common Pitfalls

1. **Origin-wide pause from one user's create burst.** NC `UserRateLimit(20/600 s)` answers 429 without `Retry-After`; `ncRequest` calls `gate.pause(origin)` for 15 min for all users. Avoid with the Tessera limiter (15/10 min) and keep creates sequential in the UI (no "share with 30 people" parallel fan-out; batch recipients one POST at a time).
2. **`ocsRequest` swallows error bodies and maps 403 to `app-password-given`.** Using it would show "use browser login" for every policy error and lose NC's message.
3. **PUT hides the reason** (`Failed to update share.`): pre-validate; map PUT 400 without password/expiry fields to generic `shareRejected`, with them to the password/expiry texts.
4. **Lenient `expireDate` parsing and timezone.** Validate strictly; the server compares in its own timezone, so near midnight the browser's "today" may be a day off: let the server message through (`shareExpiryInvalid` with NC message) instead of failing the UX; do not set `min` to tomorrow.
5. **Re-POST is not an update** and re-sends mail. Disable already-shared recipients in the picker, change via PUT.
6. **Capabilities are per user and conditional.** Missing `public.password` / `expire_date.days` keys mean "no policy", not an error. Do not cache across users; cache per `credentialKey` for at most ~60 s or fetch on dialog open.
7. **401 handling.** A 401 on any share call marks the credential dead via `ncRequest` (`credential-dead`) and `mapNcFailure` turns it into `connectionExpired` + `markExpired`; the UI already returns to the connect screen (`onExpired`). Don't catch it locally.
8. **Received shares can't be edited.** `PUT` by a recipient is 403 (`canEditShare`); only show Ändern for shares where `can_edit` is true and `uid_owner`/`uid_file_owner` is the caller. "Mit mir geteilt" actions: open, accept (if pending), leave (DELETE).
9. **Link `url` host** is built from NC's request context. If the admin saved an internal address as the Tessera NC address, links show the internal host. Document; do not rewrite.
10. **File vs folder permissions.** "Nur hochladen" and `publicUpload` on a file give 400; "Bearbeiten" on a file is 3 not 15. Decide by `entry.type`.
11. **Hide others' types.** `GET shares` returns email/federated/Talk/circle shares too; filter to types 0/1/3 (show a count or note "weitere Freigaben nur in Nextcloud") so unknown `share_with` shapes never reach the UI.
12. **Folders containing received shares can't be shared** (403 `You cannot share a folder that contains other shares`): map to a German text, don't treat as outage.
13. **Existing front-end rules:** statics-before-params route order; `FileBrowser` swallows key events inside dialogs only via `Dialog`/`EntryMenu` (`stopPropagation`): the dialog must be built on `Dialog` or typing in the sharee search triggers Entf/F2 shortcuts.

## Security Domain (ASVS L1)

| ASVS | Applies | Control |
|---|---|---|
| V2/V3 | no new auth | Existing cookie auth + `@UseModule` |
| V4 Access control | yes | `tenantId`/`userId` from `req` only; every call via `getSession(tenantId,userId)`; recipient shares are not editable by the API (NC enforces, API doesn't pre-filter by assumption) |
| V5 Input validation | yes | class-validator DTOs: `path` through `parseUserPath`; `shareType` enum {0,1,3} (link only if capability); `shareWith` `@MaxLength(255)` + no control chars; `access` enum; `expireDate` regex + real date; `password` `@MaxLength(256)`; `label` <= 255; `note` <= 500; id `^\d{1,20}$` |
| V6 Crypto | no new | Don't hash/echo passwords; not stored in Tessera |
| V7 Logging | yes | Never log request bodies, passwords, `token`/`url`; log only operation + status |
| SSRF | yes | Never fetch `url`, `api.generate` or any URL from NC answers; only fixed `/ocs/v2.php/` paths |
| Data exposure | yes | Public link URL is shown only to the user who owns the share; parsers drop unknown fields; password field from NC is the literal `redacted` and must not be forwarded as if it were a value |

Threats: STRIDE Tampering (forged permission bitmask: mitigated by server-side mapping), Information disclosure (link URL/token in logs or error extra), DoS (create bursts: limiter, list caps), Elevation (sharing others' files: NC enforces; API only passes the caller's own session).

## Validation Architecture

| Property | Value |
|---|---|
| Framework | vitest 3.2.6 (apps/api), 4.1.9 (apps/web); Biome |
| Quick run | `pnpm --filter api exec vitest run src/nextcloud-files` / `pnpm --filter web exec vitest run src/lib/nextcloud-files-api.test.ts "src/app/(portal)/modules/nextcloud-files"` (verify filter names) |
| Full suite | `pnpm --filter api test`, `pnpm --filter web test`, `tsc`, `biome check` |
| Fake transport | the `setup()` helper pattern of `nextcloud-files.service.spec.ts` (`NextcloudTransport` returning `Readable.from([...])`, assert `calls[i].url/method/body/headers`); `NextcloudCallGate` real instance |

| Behaviour | Type | File |
|---|---|---|
| URL/body built exactly (`path` encoded, `shareType[0]` keys, JSON body, `expireDate:""`) | unit | `nextcloud-shares.spec.ts` (Wave 0) |
| Parsers: user share live JSON above, link share, array vs object, `redacted`, unknown types filtered | unit | same |
| Error mapping matrix (status x sent fields) incl. 403 not leaking as 403, 429 pauses gate, 401 marks expired | unit | `nextcloud-files-shares.service.spec.ts` (Wave 0) |
| Policy derivation incl. missing keys, links disabled, enforced days | unit | same / `share-policy.test.ts` |
| Create limiter 15/10 min | unit | login-guard spec extension |
| Route order, DTO bounds | unit | controller spec extension |
| `parsePropfind` returns `shareTypes` | unit | `nextcloud-propfind.spec.ts` |
| Dialog/List/Views | component | `FileBrowser.test.tsx` pattern, new `ShareDialog.test.tsx` |
| Live: create/list/update/delete user, group, link; password-enforced policy; expiry enforced | e2e shell | new `e2e/e2e-shares.sh` next to this task, `source` the existing `261008-mzu/e2e/e2e-lib.sh` (`e2e_login`, `e2e_activate`, `e2e_set_address`, `e2e_connect_anna`, `NC_OCC`). Set policy with `NC_OCC config:app:set core shareapi_enforce_links_password --value=yes` (and `config:app:set core shareapi_default_expire_date --value=yes`, `shareapi_enforce_expire_date`, `shareapi_expire_after_n_days`) and RESET it at the end with `trap`. Key names are `[ASSUMED]` from `Manager.php` getAppValue calls (`shareapi_default_internal_expire_date`, `shareapi_expire_after_n_days`, `shareapi_internal_expire_after_n_days` seen in source; the link-password and link-expiry flags are app-config lexicon keys `SHARE_LINK_PASSWORD_ENFORCED`/`SHARE_LINK_EXPIRE_DATE_*`, exact string unverified): check with `occ config:list core` after toggling in the admin UI |
Wave 0 e2e cleanup: delete every share created (`DELETE`), leave `GET shares` empty for `anna`/`zoe`.

## Environment Availability

| Dependency | Available | Version | Note |
|---|---|---|---|
| `tessera-nc-test` | yes | Nextcloud 34.0.4, PHP 8.5, `password_policy`, `sharebymail`, `federation`, `circles` enabled | `http://172.17.0.1:18080`, users `anna / User1-Pass-12345`, `zoe` (2FA), `admin / Admin-Pass-12345`; groups `twofa`, `admin`. Brute-force whitelist set for the Docker range |
| Sharing policy in test NC | defaults | link password not enforced, no default expiry | Enforcement tests must toggle via `occ` (not yet verified which keys, see above) |
| `trusted domains` | `172.17.0.1` | | `url`/generate URLs echo the request host |

## Test-state note (honest disclosure)
I was told to stay read-only. One probe (`POST` user share with `expireDate:"31.12.2026x"`, meant to demonstrate a rejected date) was accepted by Nextcloud and created share id 1 (`/Projekte` to `zoe`). I deleted it (`DELETE shares/1`, then `GET shares` for `anna` returned `data: []`). Nothing else was changed: no `occ config` writes. Therefore the POST/PUT response shapes for LINK shares and the enforced-policy errors come from the NC source, not from a live round trip; the executor's e2e script must record them.

## Assumptions Log

| # | Claim | Section | Risk if wrong |
|---|---|---|---|
| A1 | `S` in `oc:permissions` marks a received share, `R` = reshare allowed (letters other than the observed `RGDNVCK`) | API facts | Wrong indicator / wrongly hidden Teilen action; verify with a live received share in e2e |
| A2 | Password-policy `minLength` from capabilities applies to the sharing context | Capabilities | Only a hint in the form; server decides |
| A3 | Exact `occ` keys for enforcing link password / link expiry in the e2e script | Validation | E2E setup fails; fix by checking `occ config:list core` after toggling via UI |
| A4 | Email shares (type 4) use ids that fail `^\d{1,20}$`, so id validation would block removing them | Security / Pitfall 11 | Only matters if the planner decides to list type 4; recommended not to |
| A5 | NC 429 from `UserRateLimit` carries no `Retry-After` | Pitfall 1 | If it has one, gate pause is shorter but still origin-wide; the Tessera limiter is still right |
| A6 | `can_edit`/`uid_owner` suffice to decide whether a share is changeable | Pitfall 8 | Extra 403 from NC, mapped to `shareRejected` anyway |
| A7 | Reshare bit 16 can be left out without side effects for user/group shares | Permissions | Recipients cannot reshare; matches the "simple choice" decision |

## Open Questions

1. **Module version: extend 1.0.0 or bump to 1.1.0?** Recommendation: extend the unreleased 1.0.0 (documented rule + test pin). Memory note "Version im Seed hoch" is satisfied because the seed reads the changelog.
2. **List email/federated shares read-only?** Recommendation: no, filter to 0/1/3 and mention the remainder; keeps the id/shape surface small.
3. **Password field UX for links:** required (policy) vs optional with "Passwort setzen" toggle. Recommendation: required input + "Erzeugen" button when enforced; optional toggle otherwise; never prefill.

## Sources

### Primary (HIGH)
- Nextcloud 34.0.4 server code inside `tessera-nc-test`: `/var/www/html/apps/files_sharing/lib/Controller/ShareAPIController.php` (createShare, updateShare, getShares, formatShare, parseDate, pendingShares), `.../ShareesAPIController.php`, `.../lib/Capabilities.php`, `.../appinfo/routes.php`, `/var/www/html/lib/private/Share20/Manager.php` (verifyPassword, validateExpirationDate{Internal,Link}, createShare), `/var/www/html/apps/password_policy/lib/PasswordValidator.php`
- Live probes against `http://172.17.0.1:18080` (capabilities, sharees, shares lists, error cases, PROPFIND share-types)
- Repo: `apps/api/src/nextcloud-files/{nextcloud-http,nextcloud-auth-client,nextcloud-upstream,nextcloud-call-gate,nextcloud-login-guard,nextcloud-propfind,nextcloud-dav,nextcloud-files.service,nextcloud-files.controller,nextcloud-files.types,nextcloud-files.changelog}.ts`, web `FileBrowser.tsx`, `EntryMenu.tsx`, `Dialog.tsx`, `error-text.ts`, `page.tsx`, `lib/nextcloud-files-api.ts`, `docs/anleitung-entwicklung.md` (changelog rules), `261008-mzu/e2e/{e2e-lib,nc-test-setup}.sh`

### Not consulted this session
Online Nextcloud developer manual (the running server's source was the stronger, version-exact source).

## Metadata
**Confidence:** Standard stack HIGH (no new deps); API facts HIGH for reads and errors, MEDIUM for link-share write shapes (source only); architecture HIGH; pitfalls HIGH.
**Research date:** 2026-10-09. **Valid until:** until the Nextcloud major used in production differs from 34 (re-run the capabilities and error probes against the production version before release; the production server's sharing policy was not available).