tessera-ctl/.planning/quick/261009-dkv-modul-dateien-etappe-2a-teilen-von-datei/261009-dkv-RESEARCH.md

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`)
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).