Skip to content
SHC Docs

The webdav socket on nextcloud: the backup deposit edge

Status: open design. The provider half is built (2026-08-10) and paperless carries a webdav plug. The owed list in this note is older than that work, so some of its items are done. apps/collaboration/nextcloud/webdav.socket.yaml now exists: the §6 contract (hostname/origin/davPath/url/username/password/collection/quota), the §8.1 provision job (origin refusals, converge-on-exit-1 account, quota with read-back, not-admin assertion, PROPFIND-207 capability preflight) and the §8.1 report-only teardown, gated by validate-templates and a six-test guard block. Four deliberate deviations from the letter of §8.1, each keeping its spirit: data.password is | default('')-guarded (empty is the legal shim posture, and the provision job refuses an empty render with a named cause); the provision converges the account password with occ user:resetpassword on the already-exists branch (otherwise a drifted vault value publishes a credential the preflight can only fail forever); the §10.1 home-materialisation unknown is handled in-job (occ files:scan warm-up between two PROPFINDs, refusal naming the --group fix if it survives); and the job asserts enabled + NOT-admin via user:info --output=json before the preflight. Still owed: the vars.webdav.* blocks (§8.5) in the provider’s vars.yaml + app.yaml, webdav.plug.yaml and the configure job on frappe (§8.2–8.3), the nextcloud_integration bake (§8.4), external-webdav (§9.2), the frappe-side guards, and every §11 ruling. The upstream reads below remain measured; no archive has yet been deposited end to end.

What is measured (and it is most of this document) is the other end: the upstream code the edge has to satisfy, read line by line off frappe v15.117.0, off frappe/nextcloud-integration@main, and off the Nextcloud image the package pins. Where a claim came from a command, the command is printed with it.

Sibling of 2026-08-09-frappe-nextcloud-calendar-bridge.md, which grows the app-dialect nextcloud socket. This one adds a second, protocol-named socket to the same package, and §5 is the argument that the two can coexist without repeating mailcow’s measured alias collision.


ClassMeaningMarked
MEASUREDRead off pinned source or reproduced with a command, 2026-08-09plain statement, with its command
SPECIFIEDThis document decides it; no code exists”the socket MUST…”
VERIFYA concrete assumption with the one command that settles itVERIFY
RULING OWEDAn owner decision, not an agent’s to makeRULING OWED

0.1 ★ The premise correction, first, because everything downstream moves

Section titled “0.1 ★ The premise correction, first, because everything downstream moves”

The brief for this work said “Frappe has native Nextcloud backup upload.” It does not. Measured:

Terminal window
curl -L https://codeload.github.com/frappe/frappe/tar.gz/refs/heads/version-15 | tar xz
grep -rni nextcloud frappe-version-15/frappe | wc -l # → 0
grep -rni webdav frappe-version-15/frappe | wc -l # → 0

frappe-version-15/frappe/__init__.py:54 → __version__ = "15.117.0". Zero occurrences of either word in the whole tree. The offsite backup targets frappe core actually ships are exactly three, and they are enumerated in frappe/hooks.py:267-294:

frappe.integrations.doctype.dropbox_settings.dropbox_settings.take_backups_daily
frappe.integrations.doctype.s3_backup_settings.s3_backup_settings.take_backups_daily
frappe.integrations.doctype.google_drive.google_drive.daily_backup

ls frappe-version-15/frappe/integrations/doctype/ confirms it: dropbox_settings, s3_backup_settings, google_drive. No nextcloud_settings.

What exists instead is a separate bench app, published by Frappe the organisation but shipped and versioned separately: https://github.com/frappe/nextcloud-integration: app_name: nextcloud_integration, app_publisher: "Frappe", app_license: "MIT", __version__ = '0.0.1', a single module, a single doctype, a single Python file of ~180 lines, patches.txt empty. Its only dependency is frappe (requirements.txt is the one word).

This matters for three reasons, and each one changes a decision later:

  1. The consumer side is a bake, not a config flip. Under the image-owned ruling (2026-08-08) a frappe plug mechanism is baked into the image and activated through vars, so this edge costs a third bench app in frappe/docker/Dockerfile, beside frappe_keycloak and the frappe_nextcloud the calendar bridge is landing. §8.4.
  2. The app is unmaintained-shaped. Version 0.0.1, no patches, from __future__ import unicode_literals and # -*- coding: utf-8 -*- headers throughout, Python-2-era boilerplate. It still works against v15 (§2.4 proves the four frappe APIs it calls are all present with compatible signatures), but nothing about its provenance says it is being kept in step.
  3. Its bugs are ours to route around. §2.2 and §2.5 are two measured defects in it that the socket’s published data shape can avoid entirely, which is the single strongest argument for what this socket publishes.

Nothing here is a reason not to build the edge. It is a reason to build it against what the code does rather than against what the README says, because §2.2 is a case where those two disagree.

  1. frappe/nextcloud-integration@main carries one Single doctype, Nextcloud Setting (issingle: 1), permissions System Manager only, with exactly fourteen entries in field_order, four of them layout breaks, so ten data-carrying fields, six of which are reqd: 1. §2.1 has the table.
  2. Its transport is HTTP Basic auth over WebDAV: session.auth = (self.nextcloud_username, self.get_password(fieldname='password')), session.verify = True. Methods used: PROPFIND (Depth 0), MKCOL, PUT. Success is 201 or 204 and nothing else.
  3. make_baseurl() doubles any explicit port and silently discards any path. Reproduced in §2.2 with a runnable transcription.
  4. The pinned Nextcloud image maps /remote.php/dav → the current DAV endpoint and /remote.php/webdav → the legacy one, from remote.php itself (§3.1).
  5. occ user:add on that image takes --password-from-env (NC_PASS/OC_PASS), --display-name, --group, and exits 1 with The account "<uid>" already exists. rather than no-op, the same converge-on-failure shape dav:create-subscription has (§4.3).
  6. The engine’s alias-collision warning X200931ALICOL fires only when one hostname resolves to two different services, not when two sockets share a hostname. Read off ce/modules/app/integration_render.go:1314 (§5.2).
  7. mailcow’s imap/smtp pair is the precedent for two protocol sockets on one package, and mailcow’s own files record the collision measured 2026-08-07 that this design has to not repeat.

The Nextcloud reads in §3 and §4 were taken from nextcloud:34.0.2-apache pulled fresh on 2026-08-09, which resolved to sha256:d7666d54d87c58d52869ddda36d1acbd4a7f53faf8ab6b91293daf204f3434e8. apps/collaboration/nextcloud/vars.yaml:29 pins sha256:58bc73331d541e0efe46c517ff7539e2e43427342b2a2feeb013b186fb4f3ecd. Those are different digests for the same tag; the tag has been re-pushed since the pin was taken. Nothing read here is version-sensitive (the occ argument surface and remote.php’s route map are stable across 34.x point releases), but the reads are not literally against the pinned bytes, and saying so is cheaper than being caught. VERIFY on the estate with docker run --rm --entrypoint sh nextcloud@sha256:58bc7333… -c 'grep -n "webdav" /usr/src/nextcloud/remote.php'.


ERPNext holds the books. Its backups are the only artifact whose loss is unrecoverable, and today the frappe package’s backup.yaml is the whole answer: SHC’s own capture, into SHC’s own repository, on SHC’s own schedule.

That is one basket. The estate memory records that neither production estate has an automated backup schedule at all (measured 2026-08-07), which makes the argument for a second, independent, application-authored copy stronger than it would otherwise be: a copy that a frappe operator can see, restore from a laptop, and verify without any SHC tooling in the loop.

Nextcloud is already the estate’s file plane and already federated onto people’s machines. Depositing the site’s own bench backup output there is the cheapest second basket available.

Scope, stated so it is not quietly widened later. This edge is a deposit: frappe writes archives into a WebDAV collection. It is not a restore path, not a sync, not a shared filespace, and it does not make Nextcloud a party to SHC’s backup doctrine. make migrate, never flatten; SHC’s own repository stays the primary. This is a secondary copy, and the socket’s own text must say so, because an operator who reads “backups go to Nextcloud” and concludes the SHC repository is redundant has been misled by our packaging.


2. What the consumer actually needs, measured, field by field

Section titled “2. What the consumer actually needs, measured, field by field”

Everything in this section is read off frappe/nextcloud-integration@main, file nextcloud_integration/nextcloud_integration/doctype/nextcloud_setting/nextcloud_setting.{py,json}.

issingle: 1, track_changes: 1, module: Nextcloud Integration, permissions: System Manager (create/read/write/delete/print/email/share).

fieldtypereqddefaultwhat it is
enabledCheck0the master switch; start_taking_backup returns immediately when false
nextcloud_usernameData1the Basic-auth user
passwordPassword1the Basic-auth secret; read via get_password(fieldname='password', raise_exception=False)
nextcloud_urlData1origin only; see §2.2
webdav_urlData1the DAV path, leading/trailing slashes optional
path_to_upload_folderDatacollection under the DAV root; empty ⇒ Frappe Backups
backup_frequencySelect1Dailyoptions are exactly Daily and Weekly
backup_filesCheck0also upload the public/private file tarballs
send_notifications_toData (Email)1recipient of the status mail
send_email_for_successful_backupCheck0failures always mail; successes only when set

★ Six reqd: 1 fields is a packaging constraint, not trivia. A configure job that writes only the four connection fields and leaves send_notifications_to empty will fail the Single’s save with a mandatory-field ValidationError. The plug MUST carry an address; §8.2 defaults it from the already-bound smtp edge and refuses with a named cause when there is none.

★ backup_frequency has no “off”. Unlike s3_backup_settings, whose frequency Select includes None, this one offers Daily|Weekly only. The only way to stop scheduled uploads is enabled = 0. That is what the unintegration job must write (§8.3), not a frequency change, which cannot express it.

2.2 ★ The URL shape, and the two defects that fix the socket’s data keys

Section titled “2.2 ★ The URL shape, and the two defects that fix the socket’s data keys”

make_baseurl() is seventeen lines including its signature, and both of this edge’s hard constraints live in them. Transcribed verbatim and run:

def make_baseurl(nextcloud_url, webdav_url):
vurl = urlparse(nextcloud_url)
if not vurl.scheme: return None
if not vurl.netloc: return None
if not vurl.port:
port = 443 if vurl.scheme == 'https' else 80
base_url = '{0}://{1}:{2}'.format(vurl.scheme, vurl.netloc,
vurl.port if vurl.port else port)
...

urlparse(...).netloc already contains the port, and the format string appends it again. Measured output:

nextcloud_urlresulting base URL
https://cloud.example.comhttps://cloud.example.com:443/remote.php/dav/files/admin/
http://prod.nextcloud.mystackhttp://prod.nextcloud.mystack:80/remote.php/dav/files/admin/
http://prod.nextcloud.mystack:80http://prod.nextcloud.mystack:80:80/… ❌
https://cloud.example.com:8443https://cloud.example.com:8443:8443/… ❌
https://cloud.example.com/subpathhttps://cloud.example.com:443/remote.php/dav/files/admin/ ❌ path gone
prod.nextcloud.mystackNone ⇒ error_log.append('Nextcloud URL incorrect')

Three constraints fall straight out, and each one is a socket data decision rather than a job-side workaround:

  1. The published origin MUST carry no explicit port. Not :443, not :80, not a non-standard one. A ported origin is not “slightly wrong”; it produces an authority no resolver can parse and every upload fails. Fortunately nextcloud.socket.yaml’s internalUrl is already port-less (http://{{ environment }}.nextcloud.{{ stack }}), so the in-fabric posture is safe by construction. The public posture is not: vars.publicUrl is operator-authored and may carry anything. §8.1 makes the socket refuse a ported origin rather than publish it.
  2. A path-routed Nextcloud cannot be expressed at all. The path is discarded silently, so the archives would be PUT at the wrong origin and 404. This is the same refusal nextcloudPicker.plug.yaml already makes for a path-routed picker, for the same reason: one constant cannot carry two meanings, and degrading is worse than refusing. Refuse, and name it.
  3. The origin and the DAV path are two fields, so publish two keys. The consumer’s configuration surface is nextcloud_url + webdav_url. A socket that published only a joined url would force the configure job to split it in POSIX sh, parameter-expansion string surgery on a URL, which is exactly the fragile thing nextcloudPicker.plug.yaml had to write and then guard. Publishing the split as the primitive costs one data key and removes the shell entirely. §6.

Leading/trailing slashes on webdav_url are normalised by make_baseurl ('/remote.php/dav/files/admin', 'remote.php/dav/files/admin/' and '/remote.php/dav/files/admin/' all produce the same base). So the socket may publish whichever form reads best; it must still pick one and stick to it, because §8.5’s read-back compares stored strings.

PROPFIND <base><folder> Depth: 0 allow_redirects=False
404 and path_to_upload_folder set → frappe.throw('Given "Path to upload folder" does not exist')
404 and it is unset → MKCOL <base>Frappe Backups
PUT <base><folder>/<filename> allow_redirects=False
201 or 204 → "Success"; anything else → "Failed"

Four consequences worth stating, because three of them are the difference between an edge that works and one that reports success while doing nothing:

  • MKCOL creates one level. A path_to_upload_folder naming a nested collection whose parent does not exist gets a 409 from the server, and the code only branches on 404. So either the operator pre-creates the tree, or the collection is single-segment. The socket’s own default MUST be single-segment.

  • allow_redirects=False everywhere. An ingress that 301s http→https, or a Nextcloud behind a redirecting proxy, produces a 301 which is neither 201 nor 204 ⇒ "Failed". In-fabric plain HTTP has no redirect and is the safe posture; §8.1 says so.

  • session.verify = True. A public origin fronted by a private CA fails TLS verification. upload_backup swallows every exception and returns the string "Failed" with no cause, so the operator gets a failure email naming nothing. check_for_upload_folder does not catch, so its TLS error at least reaches the traceback in the failure mail. In-fabric HTTP sidesteps the whole class.

  • ★ An absent file is scored as a success. upload_backup opens with if not os.path.exists(filebackup): return, an implicit None. The caller compares if db_response == 'Failed', and None == 'Failed' is false, so a file that was not there is indistinguishable from an upload that worked, and send_email_for_successful_backup will happily mail “Backup Uploaded Successfully”. Narrow (it needs the archive to vanish between generation and upload) but real, and it is the reason §8.5’s read-back verifies against Nextcloud, never against the app’s own report.

    Its sibling is safe: when get_recent_backup returns None, os.path.exists(None) raises TypeError (verified on CPython 3.14.4: “stat: path should be string, bytes, os.PathLike or integer, not NoneType”), which the outer except Exception turns into a failure email with a traceback. Loud, not silent.

2.4 It still fits frappe v15, checked, not assumed

Section titled “2.4 It still fits frappe v15, checked, not assumed”

The app imports four things out of frappe. All four are present in 15.117.0 with compatible signatures:

importv15 locationsignature check
frappe.utils.backups.new_backupbackups.py:587new_backup(older_than=6, ignore_files=False, …, force=False, …); the app passes ignore_files= and force= by keyword ✓
BackupGenerator.get_recent_backupbackups.py:258get_recent_backup(self, older_than, partial=False); the app passes older_than=24*30 ✓
offsite_backup_utils.send_emailoffsite_backup_utils.py:11send_email(success, service_name, doctype, email_field, error_status=None); the app’s 4- and 5-arg calls both fit ✓
offsite_backup_utils.validate_file_sizesame filevalidate_file_size() ✓

★ And one behaviour worth recording because it looks like a bug and is not. validate_file_size() sets frappe.flags.create_new_backup = True, then clears it to False when the newest existing database archive exceeds 1 GB. prepare_backup passes that flag as force=. So on a site over 1 GB the app reuses a dump taken in the last 6 hours instead of taking a fresh one (new_backup’s default older_than=6 → BackupGenerator.get_backup(6, …, force=False)). On a daily cadence the previous dump is 24 hours old, so a fresh one is taken anyway. It is a de-duplication, not staleness, but it does mean “Backup Now” twice in a row on a large site uploads the same archive twice, and an operator proving the edge should not read that as a failure.

get_recent_backup(older_than=720) is a maximum staleness, not a lookback: old_enough() returns the file only when is_file_old(path, 720) is false. An archive older than 30 days is returned as None, which lands on the loud TypeError path above.

hooks.py registers exactly two scheduler events:

scheduler_events = {
"daily": ["…nextcloud_setting.daily_backup"],
"weekly": ["…nextcloud_setting.weekly_backup"],
}

and each calls take_backups_if(freq), which compares frappe.db.get_single_value("Nextcloud Setting", "backup_frequency") to its own name. So a Weekly setting makes the daily hook a no-op, and vice versa.

This depends on the frappe scheduler being live, which the calendar-bridge document already flags as a restore-carried hazard: frappe.exporter.yaml names pause_scheduler and scheduler_enabled as source-deployment posture a restore must not carry in. A paused scheduler makes this edge a configuration that never fires and never says so. §8.5’s preflight asserts it, and §9’s acceptance list proves it with a manual trigger rather than by waiting a day.

take_backup() is @frappe.whitelist()-decorated and enqueues start_backup on the long queue with timeout=1500. That is the handle an acceptance test uses; it needs no UI.

★ There is no retention. Every run PUTs a fresh timestamped filename into one collection and nothing ever deletes. The collection grows without bound inside whatever quota the deposit account has. A quota is therefore not a nicety; it is the only backstop, and §4.2 makes setting one part of the provision. RULING OWED in §11 on whether SHC should also prune.


docs/app-development/plugs-and-sockets.md states the rule and, more usefully, states the test. Both questions are asked and answered here.

3.1 Question 1: could a second, unrelated implementation serve it?

Section titled “3.1 Question 1: could a second, unrelated implementation serve it?”

WebDAV is RFC 4918, an IETF wire protocol with many independent servers (Apache mod_dav, nginx’s dav module, ownCloud, Seafile, Synology, and every commercial “WebDAV endpoint” a consumer might be pointed at). The consumer in §2 does not know it is talking to Nextcloud: it sends PROPFIND, MKCOL and PUT with Basic auth and branches on 201/204/404. Nothing in nextcloud_setting.py reads an OCS route, a capability document, or any Nextcloud-specific header. The one Nextcloud-flavoured thing it does (session.headers.update({"OCS-APIRequest": "true"})) is set on a session that only ever performs DAV verbs, where the header is inert.

Measured from the pinned image, Nextcloud’s own DAV surface is two mounts, read off /usr/src/nextcloud/remote.php:

'webdav' => 'dav/appinfo/v1/webdav.php', # /remote.php/webdav (legacy)
'files' => 'dav/appinfo/v1/webdav.php', # /remote.php/files (legacy alias)
'dav' => 'dav/appinfo/v2/remote.php', # /remote.php/dav (current)

The current endpoint’s files collection is /remote.php/dav/files/<uid>/, the form Nextcloud’s own Files settings pane prints, and the form the app’s README names (imprecisely, as /remote.php/dav/files/{email_address}/; the path segment is the uid, which equals the email only for accounts created with an email as the login).

★ The legacy /remote.php/webdav endpoint takes no uid; it serves the authenticated principal’s own root. That is a genuinely useful property for a socket whose whole job is substitutability, because it makes the published path independent of the account name. It is not the recommended endpoint though, and VERIFY before adopting it:

Terminal window
curl -u "$USER:$APPPASS" -X PROPFIND -H 'Depth: 0' \
http://<nc>/remote.php/webdav/ -o /dev/null -w '%{http_code}\n' # expect 207

Answer to question 1: yes.

3.2 Question 2: is external-webdav nameable?

Section titled “3.2 Question 2: is external-webdav nameable?”

Trivially. apps/standalone/ already carries external-imap, external-smtp, external-s3, external-postgres, external-mysql, external-mongodb, external-redis, external-oidc, external-llm, nine shims, each serving a socket stem identical to its own suffix, each publishing coordinates an operator pasted in and running no service of its own. external-webdav would publish an origin, a path, a username and a password; it is a vars.yaml and a socket file. That is precisely the shape of a WebDAV deposit target: an operator with a Hetzner Storage Box, an ownCloud, or a rented WebDAV space pastes four values and the frappe plug cannot tell the difference.

That is question 1 made operational, and the shim passes it without strain.

Answer to question 2: yes.

Because the socket’s own header already drew the line and it lands on the other side of it:

a SINGLETON socket carrying the bare app name … this is Nextcloud’s own surface (WebDAV under /remote.php/dav, OCS under /ocs/v2.php, the bearer contract user_oidc’s oidc plug configures), not a substitutable wire protocol.

The nextcloud socket’s contract is “act inside Nextcloud with Nextcloud’s own admin authority”: OCS user enumeration, an admin app password, a read-back of a dav app-config knob. Every one of those keys is meaningless to a second implementation. A backup deposit is the opposite: it needs a URL, a login and a password, and it needs to not care what is behind them.

The tell is the plug. A frappe deployment binding -i nextcloud=<stack> gets the discovery half of an app-dialect socket and, if it declares a label, an admin-equivalent credential (the socket says so in as many words: “IT IS NOT A SCOPED CAPABILITY, AND CALLING IT ONE WOULD BE A LIE”). Asking for that in order to upload a tarball would be the estate’s most privileged secret issued to its least privileged verb. §4 is that argument in full.

This is also the second half of a rule the catalog already applies to mailcow: one app, one dialect socket (mailcow, the REST admin API) plus protocol sockets beside it (smtp, imap) that external-* shims can serve. Nextcloud gets exactly the same treatment (nextcloud for the dialect, webdav for the protocol), and for exactly the same reason.


4. The credential, and no, the existing grant does not cover it

Section titled “4. The credential, and no, the existing grant does not cover it”

4.1 What the grant would give, and why it is the wrong shape

Section titled “4.1 What the grant would give, and why it is the wrong shape”

nextcloud.socket.yaml’s grant-nextcloud-admin mints a 72-character app password on vars.adminUser via occ user:auth-tokens:add. Mechanically it would work here: Nextcloud accepts app passwords as the password half of Basic auth on DAV, and /remote.php/dav/files/<adminUser>/ is a writable collection. Nothing would fail.

That is the problem. Measured, from the socket’s own header:

occ exposes no --scope on this command, so the token carries the admin account’s full authority: a holder can read every file in the instance and create or delete users.

The capability being purchased is “append files to one collection”. The credential on offer is “read every file in the instance and create or delete users”. That gap is not a rounding error, and unlike the calendar bridge’s observation problem there is no argument from necessity: the calendar bridge needs /cloud/users, which is admin-or-subadmin only, so the admin grant is the only headless path Nextcloud offers. A DAV deposit needs no admin surface at all. A plain user’s own DAV home is the scoped capability, and it already exists.

So the answer to “does the existing nextcloud admin grant cover it” is: yes mechanically, no doctrinally, and this is one of the rare cases where those diverge and the doctrinal answer should win, because taking the grant here means holding admin authority in a job whose entire job is PUT.

4.2 What the socket provisions instead: SPECIFIED

Section titled “4.2 What the socket provisions instead: SPECIFIED”

A dedicated, non-admin, quota-bounded Nextcloud account whose only purpose is to own the deposit collection. Measured against the pinned image:

Terminal window
# core/Command/User/Add.php on nextcloud:34.0.2-apache
occ user:add --password-from-env --display-name "SHC backup deposit" <uid>
# uid must match [a-zA-Z0-9_@-]+ ("must only contain a-z, A-Z, 0-9, -, _ and @")
# password read from NC_PASS, falling back to OC_PASS
# exits 1, "The account "<uid>" already exists."; never a no-op
occ user:setting <uid> files quota "50 GB"

Two of those lines are load-bearing:

  • ★ user:add fails rather than no-ops on an existing account, exactly like dav:create-subscription. So the provision job creates, reads the failure text as converged, and never asks “does it exist” on the happy path. Same measured shape, same converger discipline, and it is worth noticing that this is now the second place in this package where Nextcloud’s CLI expresses idempotence as exit 1.
  • The quota is the only bound on §2.5’s unbounded growth. user:setting <uid> files quota <value>; Setting.php on the same image takes <uid> <app> <key> <value> with --update-only, --delete and --error-if-not-exists options. Setting it is part of the provision, not an operator afterthought.

VERIFY, and it decides whether the provision needs a second step: user:add calls Filesystem::init($uid, '') only when --group is passed (Add.php, the if (!empty($groups)) branch). A fresh account with no group may therefore have no materialised home until something touches its filesystem. The app’s own first act is a PROPFIND on the collection, which should force it, but prove it rather than assume:

Terminal window
occ user:add --password-from-env --display-name t probe-user
curl -u 'probe-user:<pw>' -X PROPFIND -H 'Depth: 0' \
http://localhost/remote.php/dav/files/probe-user/ -o /dev/null -w '%{http_code}\n'
# expect 207 on the first call, not 404

If it does not, the fix is one flag: give the account a group.

4.3 Why the credential is published, not minted per consumer

Section titled “4.3 Why the credential is published, not minted per consumer”

The nextcloud socket mints per consumer over the mint-and-return channel, keyed on an opt-in label. This socket does not, and the reason is the same one imap.socket.yaml gives for its contract (1):

SHARED RELAY MAILBOX: username/password. One credential, the stack’s own noreply mailbox, provisioned by mailcow-provision-smtp. Correct for SYSTEM consumers …

A protocol socket publishes coordinates in data:. That is what makes external-webdav possible at all: a shim that runs no service cannot mint anything, so any key only a real provider could produce is a key the shim must publish empty and every consumer must guard. Minting would make the socket un-shimmable, which is the one property §3 spent its whole argument establishing.

The cost, stated plainly: one credential, shared by every consumer that binds webdav on this provider. Two frappe stacks depositing into one Nextcloud share a login and a collection. That is acceptable for a deposit account whose authority is one directory, and it is not acceptable for anything with a wider reach, which is the boundary the socket header must draw, in the same voice imap.socket.yaml draws it.

RULING OWED (§11): whether a per-consumer app password on the deposit account, gated on an optional label exactly as the nextcloud socket gates its admin grant, should be the growth path. It is cheap (the same occ user:auth-tokens:add, just on a non-admin uid instead of admin), and it would give per-consumer revocation without touching the shared account. It is proposed, not designed, because nothing needs it yet and a second consumer is what should trigger it.


5. Two sockets, one app, and the alias collision, measured

Section titled “5. Two sockets, one app, and the alias collision, measured”

This is the mechanical question the design has to clear before it can ship, so it gets its own section and an exact answer.

5.1 What mailcow measured, and why it hurt

Section titled “5.1 What mailcow measured, and why it hurt”

Both mailcow protocol sockets publish the same rendered hostname, and both files carry the identical warning:

the engine attaches data.hostname as a network alias on this service, and smtp.socket.yaml attaches the SAME rendered hostname on postfix-mailcow; docker DNS returns both A records in rotating order and a wrong-A connect REFUSES (measured 2026-08-07: dovecot answering :587 refused, postfix answering :993 refused).

The failure is not “the hostname is ambiguous”. It is that the two sockets front different services, so half the connections land on a container that is not listening on the port the caller dialled. The files also record why neither obvious fix is available there: distinct in-fabric names break TLS verification and off-fabric dials of the same socket data, and a fronting TCP proxy would sit in every mail path.

5.2 The engine’s guard, and exactly when it fires

Section titled “5.2 The engine’s guard, and exactly when it fires”

ce/modules/app/integration_render.go, in the loop that attaches socket hostnames as network aliases:

if prior, clash := aliasedBy[hostname]; clash && prior != serviceName {
corelog.Warn(ctx, X200931ALICOL(stack, hostname, prior, serviceName))
} else {
aliasedBy[hostname] = serviceName
}

and the error’s own header (errors.go:1759):

two sockets of one provider package render the SAME hostname onto DIFFERENT services … The attach proceeds; half-working resolution beats none, but the collision is a package defect only its author can fix.

★ The predicate is prior != serviceName. Two sockets sharing a hostname and resolving to the same service take the else branch and re-record the same mapping: no warning, no collision, nothing to fix. The hazard is service divergence, not socket count.

5.3 Why this pair is safe, and how to keep it that way

Section titled “5.3 Why this pair is safe, and how to keep it that way”

apps/collaboration/nextcloud/compose.yaml declares three services: nextcloud, valkey, nextcloud-pgclient. Only one of them speaks HTTP, and both DAV and OCS are served by the same PHP application on the same port. So webdav.socket.yaml and nextcloud.socket.yaml front the same service and the guard cannot fire.

That safety is conditional on one line, and the line is easy to omit:

service: nextcloud # REQUIRED. Without it resolveSocketService falls to the
# socket file stem ("webdav", not a service here) and
# then to the sorted-first heuristic, which reports
# X200930SOKSVC on every install.

Measured from resolveSocketService (integration_render.go:1776): declared name first, then the socket stem, then sort.Strings(names)[0] with guessed=true. Sorted-first here happens to be nextcloud ("nextcloud" < "nextcloud-pgclient" < "valkey"), so omitting service: would still resolve correctly, and would still emit a soft warning on every install, and would still be one renamed service away from silently pointing the socket at nextcloud-pgclient. Declare it.

The remaining choice is whether webdav publishes the same hostname or its own. The same one ({{ environment }}.nextcloud.{{ stack }}), because it is literally the same HTTP endpoint, because two aliases on one service buy nothing, and because a webdav-flavoured alias would invite a future reader to believe the two sockets front different things. A guard is added (§8.6) that asserts both sockets in this package resolve to the same service:, so the day someone splits DAV onto a second container the tree goes red before the estate does.

5.4 What the mailcow precedent actually teaches

Section titled “5.4 What the mailcow precedent actually teaches”

Not “avoid two sockets per package”; mailcow ships three and the catalog is better for it. The lesson is narrower and it is the one this design applies: the hostname is a property of the fronting service, not of the socket. Two sockets may share a hostname iff they share a service. When they do not, the package owes either distinct hostnames or a fronting service, and mailcow’s own files are the record of what it costs when neither is available.


schema:
socket:
hostname@string!: In-fabric hostname the engine aliases onto the provider's HTTP service
origin@url!: Scheme + host, NO PORT and NO PATH; see the constraint at the data key
davPath@string!: Absolute DAV path under that origin, with a leading and trailing slash
url@url!: Convenience join, `origin + davPath`. Equal by construction; never re-derive it
username@string: Deposit account login (empty when the provider grants no account)
password@secret: Deposit account secret (empty likewise); guard every read with `| default('')`
collection@string: Collection under davPath the consumer should write into (single segment)
quota@string: Advertised quota on the deposit account, informational; empty means unknown

Notes that belong on the keys themselves, each because something measured demands it:

  • origin carries no port and no path. Not a preference: §2.2 measured a consumer that doubles the port and discards the path. Any provider serving this stem inherits the constraint, so it belongs in the schema text rather than in one consumer’s job.
  • origin and davPath are the primitives; url is the convenience. The known consumer configures the two halves separately, and splitting a URL in POSIX sh is precisely the fragility nextcloudPicker.plug.yaml documents. Publishing all three costs one string and removes an entire class of job-side parsing.
  • username/password are optional and every consumer MUST | default('')-guard them, the contract imap.socket.yaml states for its mailcow-only keys, for the same reason: a shim publishes what the operator pasted and nothing else.
  • collection is single-segment by default, because MKCOL creates one level (§2.3) and the consumer frappe.throws on a missing multi-level path.
  • quota is advertised, not enforced, the same posture calendarRefreshRate takes on the sibling socket. It tells a consumer how much room it has; it promises nothing.

Deliberately absent, so it is not relitigated:

  • No OCS anything. OCS is the dialect socket’s business. A webdav consumer that wants to enumerate users is in the wrong socket.
  • No label and no mint channel. §4.3. Adding one later is additive and is the growth path the ruling in §11 decides.
  • No publicUrl. A deposit that leaves the fabric is a different posture with different failure modes (TLS verification, redirects, egress policy). If it is wanted, it is vars.webdav.origin on the provider, published through the same origin key, and §8.1’s ported-origin refusal is what keeps it honest.

7. How it coexists with the nextcloud socket at bind time

Section titled “7. How it coexists with the nextcloud socket at bind time”

One provider now offers two stems, and a consumer picks by name. Three mechanics decide what that feels like, and all three already exist:

7.1 Auto-match still works, and still only when it is unambiguous. -i <provider> auto-matches “only if exactly one of the consumer’s plugs matches one of the provider’s sockets by name” (plugs-and-sockets.md, the integration-ref table). A frappe stack that declares both nextcloud.plug.yaml (calendar) and webdav.plug.yaml (backup) therefore cannot be bound with a bare -i nextcloud=<stack>; it must name the plug: -i webdav=<stack>, -i nextcloud=<stack>. That is correct behaviour, and the packaging owes it a sentence in the app README rather than an operator discovering it from a refusal.

7.2 The two edges are independent and must stay that way. Binding webdav grants no admin credential; binding nextcloud deposits no backups. Neither plug may read the other’s data. A consumer that wants both binds both, and required: false on each keeps a missing one from blocking an ERP install.

7.3 They share exactly one thing: the provider’s readiness. Both need status.php to answer installed:true and maintenance:false. The existing socket already waits on both (its grant job polls for ~5 minutes and refuses with a named cause). webdav’s discovery job should reuse the same context: http probe against internalUrl/status.php, same shape, same budget, no new mechanism.


8. The exact SHC surfaces: all SPECIFIED, none of them exist

Section titled “8. The exact SHC surfaces: all SPECIFIED, none of them exist”

8.1 apps/collaboration/nextcloud/webdav.socket.yaml: new

Section titled “8.1 apps/collaboration/nextcloud/webdav.socket.yaml: new”
service: nextcloud # REQUIRED; §5.3
data:
hostname: "{{ environment }}.nextcloud.{{ stack }}"
origin: "{{ vars.webdav.origin | default('http://' ~ environment ~ '.nextcloud.' ~ stack) }}"
davPath: "/remote.php/dav/files/{{ vars.webdav.user | default('shc-deposit') }}/"
url: "{{ vars.webdav.origin | default('http://' ~ environment ~ '.nextcloud.' ~ stack) }}/remote.php/dav/files/{{ vars.webdav.user | default('shc-deposit') }}/"
username: "{{ vars.webdav.user | default('shc-deposit') }}"
password: "{{ vars.webdav.password }}" # @secret, ref+vault://…?autogen
collection: "{{ vars.webdav.collection | default('backups') }}"
quota: "{{ vars.webdav.quota | default('') }}"

url repeats the join rather than referencing origin because a data key cannot reference a sibling data key, the same constraint the existing socket records where it spells internalUrl and ocsUrl out twice, and gitlab’s socket does the same. A guard (§8.6) asserts the two spellings agree.

jobs.discovery: one context: http probe on {{ integration.socket.data.origin }}/status.php, max_retries: 60, retry_interval: 3. Same as the sibling socket’s.

jobs.integration: provision-webdav-deposit, context: service, service: nextcloud, user: www-data (occ refuses to run as root; www-data owns config.php on this image). No timeout: field; the socket integration job struct has none, so writing one parses and then vanishes; the waits carry their own budgets. In order:

  1. Refuse a ported or path-carrying origin, loudly. §2.2 is not a warning, it is a hard stop:

    Terminal window
    # A port survives into the consumer's URL builder twice and a path not at
    # all; both produce an authority no upload can reach. Refusing here is the
    # only place the operator still has the value in their hand.
    case "$${ORIGIN}" in
    http://*:*/* | https://*:*/* | *://*:[0-9]*) BAD=port ;;
    esac
    REST="$${ORIGIN#*://}"
    case "$${REST}" in */*) BAD=path ;; esac

    with a message naming which of the two it is and what to set instead.

  2. Wait for occ status --output=json to report installed:true and maintenance:false, exactly as grant-nextcloud-admin does and for the reason it records: during an occ upgrade, status.php still says installed while every HTTP route answers 503.

  3. Provision the deposit account, reading The account "<uid>" already exists. (exit 1) as converged, never as failure. NC_PASS from the @secret var; --display-name set; quota applied when vars.webdav.quota is non-empty.

  4. Read the account back; occ user:info <uid> --output=json must show it enabled, and it must not be in the admin group. The account being accidentally admin is the one outcome that silently converts a scoped capability into the thing §4.1 refused; assert against it rather than assume the create was clean.

  5. Prove the capability, not the credential, the discipline the sibling socket already enforces on its OCS preflight. PROPFIND the collection as the deposit account over http://localhost, with Host: read off occ config:system:get trusted_domains 0 (the image installs trusted_domains[0] = localhost; an untrusted Host is answered with an error page). A 207 is the proof. MKCOL the collection when the PROPFIND is 404, then PROPFIND again; the write is never trusted by its exit code.

  6. Print a one-line summary: provisioned / converged, quota, collection.

jobs.unintegration: report-webdav-deposit-retained. It reports, it does not delete, and the reason is the same one that keeps lifetime: managed off the sibling’s revoke job, arrived at from the other side: this collection holds an operator’s backups. Deleting a user-visible archive on a detach is the destructive half of the class the estate has already been burned by. So the job says what remains, names the two commands (occ user:delete <uid>, or empty the collection from the Files UI), and exits 0. RULING OWED in §11 on whether it should at minimum disable the account, which stops future deposits without destroying past ones.

8.2 apps/platform/frappe/webdav.plug.yaml: new

Section titled “8.2 apps/platform/frappe/webdav.plug.yaml: new”
required: false # a backup target must never block an ERP install
services:
- frappe-web # the site DB connection and the bench live here;
# frappe DIALS OUT to Nextcloud, so no inbound alias
# is needed and none is claimed
data:
collection: "{{ vars.webdav.collection | default('') }}" # empty ⇒ the socket's
notifyEmail: "{{ vars.webdav.notifyEmail | default('') }}" # ⇒ reqd field, §2.1
frequency: "{{ vars.webdav.frequency | default('Daily') }}" # Daily|Weekly ONLY
backupFiles: "{{ vars.webdav.backupFiles | default(false) }}"

⚠ {{ stack }} in a plug data: render is the PROVIDER’s stack, not this one (sonarqube/gitlab.plug.yaml documents the trap; ce builds plugCtx with "stack": sp.ProviderStackName). Nothing above derives from stack, and nothing added later may; tenant is the consumer’s, stack names the Nextcloud.

jobs.post_deployment carries the configure job (§8.3); jobs.unintegration carries the disable job.

frappe-configure-webdav-backup, context: service, service: frappe-web. It follows frappe-configure-keycloak-connector and frappe-install-picker-client-script because both already solved the shape:

  1. Refuse if the app is not on the bench, in the IMAGE-OWNED language the bats guard pins, never suggesting a vdeployment, never running bench get-app:

    Terminal window
    if ! ./env/bin/python -c "import nextcloud_integration" 2>/dev/null; then
    echo "the webdav backup edge was requested but nextcloud_integration is not on this bench." >&2
    echo "Plug mechanisms are IMAGE-OWNED (owner ruling 2026-08-08): baked in, activated" >&2
    echo "through vars, never installed as vdeployments. Point images.frappe at an image" >&2
    echo "that bakes nextcloud_integration." >&2
    exit 1
    fi
  2. bench --site <s> install-app nextcloud_integration when absent. Safe per the corrected rule in the Dockerfile header: the code is already importable, so registration has no import window.

  3. Write the Single. frappe.client.set_value on a Single works, but all six reqd fields must be present in one save or the mandatory check fails, so the job builds one payload and writes it once, and it builds it with json.dumps + ast.literal_eval for the reason the picker plug records: bench execute --kwargs is evaluated as a Python literal, not parsed as JSON, so true/false/null are NameErrors and every boolean must be an int.

  4. Read back and fail loudly; re-read the stored Single and assert enabled == 1, that nextcloud_url is exactly the published origin, and that the stored password digest matches the one sent (never echo it). House discipline: no write in this catalogue is trusted by its exit code, and §2.3’s silent-success path is the local reason.

  5. Prove the deposit end to end, once. bench --site <s> execute nextcloud_integration.…nextcloud_setting.take_backup enqueues on the long queue; the job then polls the collection over WebDAV for a new object. This is the step that catches a paused scheduler, a wrong quota, a redirecting ingress and a TLS refusal, all four of which otherwise present as “configured, and nothing ever arrives.”

Why activation lives here and not in vars.activateApps. Same argument the calendar bridge makes: activateApps is for apps every site should carry regardless of edges. This one is meaningful only when a webdav edge exists, and activating it estate-wide would put a backup uploader on benches with nowhere to upload. Edge-scoped activation, edge-scoped teardown.

8.4 The bake, and the cost nobody should be surprised by

Section titled “8.4 The bake, and the cost nobody should be surprised by”

frappe/docker/Dockerfile gains a third bench app, in the shape the first two established (the file already carries frappe_keycloak at a pinned sha and frappe_nextcloud at REPLACE_WITH_PUBLISHED_SHA, the calendar bridge’s placeholder):

ARG NEXTCLOUD_INTEGRATION_REPO=https://github.com/frappe/nextcloud-integration.git
ARG NEXTCLOUD_INTEGRATION_REF=<commit sha, never a branch>

with the same git init / fetch --depth 1 / test "$(git rev-parse HEAD)" = assertion, the same ./env/bin/pip install -e under USER frappe, the same separate RUN proving import nextcloud_integration against ./env/bin/python, and nothing written under sites/ or logs/ (tests/unit/ci/frappe_image_volume_writes_test.go enforces that, because Docker does not: under BuildKit a write to a VOLUME path persists into the published image).

★ This app is a third-party pin at 0.0.1 with no release cadence, so the sha is the version and there is nothing else to track. record-versions.sh walks the bench and will pick it up; it must also be added to the provenance manifest’s required-app list beside frappe, erpnext, frappe_keycloak and frappe_nextcloud, or tests/unit/catalog/image_provenance_test.go will happily pass an image that is missing it.

★ And the trap that must be stated with the delivery, every time: the bench volume is seeded once. On an existing bakeApps: false deployment (the default, and what both live production benches run), .seeded already exists, so the new app does not arrive and there is no error. version-drift reports stale and names it, which is the only reason the no-op is visible. Delivering this to an existing vapp-mode bench needs a deliberate, consented step. Bumping the pin is not that step and must not be reported as one.

★ A vendoring question this raises and does not answer. Three baked bench apps, one of them third-party and dormant, is the point at which “which apps does the SHC frappe image carry, and who decides” stops being obvious. That is a packaging ruling, not a socket decision, and it is §11.4.

8.5 apps/platform/frappe/vars.yaml: additions

Section titled “8.5 apps/platform/frappe/vars.yaml: additions”
webdav:
collection: "" # empty → the socket's own default
notifyEmail: "" # empty → derived from the smtp edge; refused if neither
frequency: "Daily" # Daily | Weekly ONLY; the doctype Select has no third option
backupFiles: false # public + private file tarballs alongside the DB dump

and on the provider, apps/collaboration/nextcloud/vars.yaml:

webdav:
origin: "" # empty → the in-fabric http origin. If set: NO PORT, NO PATH.
user: shc-deposit # [a-zA-Z0-9_@-]+, occ user:add's own character class
password: "ref+vault://webdav_deposit_password?autogen"
collection: backups # single segment: MKCOL creates one level
quota: "50 GB" # the ONLY bound on unbounded growth; this edge never prunes

with matching vars: type declarations in each app.yaml, each carrying the constraint that governs it.

testasserts
apps/collaboration/nextcloud/tests/tests.batswebdav.socket.yaml declares service: nextcloud, and every *.socket.yaml in the package declares the same service (the §5.3 invariant, stated as a property so a future third socket is caught)
samedata.url equals data.origin ~ data.davPath (the sibling-key duplication of §8.1)
samedata.origin’s default renders with no : after the host and no path segment
samethe unintegration job never deletes a collection or a user (grep for user:delete / DELETE verbs)
apps/platform/frappe/tests/tests.batsthe new plug carries no vapp: (covered by the existing glob), required: false, services: pins frappe-web, the configure job says IMAGE-OWNED and never bench get-app
samethe plug’s data: uses tenant and never stack
sameevery socket read in the configure job is `
tests/unit/catalog/image_provenance_test.gothe Dockerfile app set and imageVersions agree (existing test, new row)

9.1 Phase 1: a working deposit. Buildable today.

Section titled “9.1 Phase 1: a working deposit. Buildable today.”

What ships: an operator runs shc update <frappe-stack> -i webdav=<nc-stack> and the site’s daily backup lands in a quota-bounded Nextcloud collection, with a failure email if it does not.

#DeliverableWhereNew component?
1webdav.socket.yaml + provision job + report-only teardownapps/collaboration/nextcloud/no, a new file using idioms already in the package
2vars.webdav.* on the providerapps/collaboration/nextcloud/vars.yaml, app.yamlno
3The nextcloud_integration bake + pinfrappe/docker/Dockerfile, apps/platform/frappe/vars.yamlyes, a third baked bench app
4webdav.plug.yaml + vars + the configure jobapps/platform/frappe/no
5The guardsboth tests.bats, image_provenance_test.gono

★ “No new component” is true of the SHC side and only the SHC side. There is no broker, no sidecar, no vApp, no daemon, no credential mint and no new Go. But item 3 is a real image change with a real delivery trap (§8.4), and unlike the calendar bridge there is no new code to write; the bench app already exists and is MIT. The honest summary is: one new socket, one new plug, one third-party pin.

Acceptance for phase 1 (each line is a command, not a feeling):

  1. occ user:info shc-deposit --output=json → enabled, quota as configured, not in the admin group.
  2. A second shc update provisions nothing and reports “converged”, the idempotency assertion, and the one most worth automating, because §4.2’s converge-on-exit-1 is the only thing making it true.
  3. bench --site <s> execute frappe.client.get_value --kwargs "…" shows the Single with enabled = 1 and nextcloud_url exactly equal to the socket’s published origin, string-equal, because a :443 that slipped in would look right and upload nothing.
  4. bench --site <s> execute nextcloud_integration.nextcloud_integration.doctype.nextcloud_setting.nextcloud_setting.take_backup then, within a few minutes, curl -u shc-deposit:<pw> -X PROPFIND -H 'Depth: 1' <url><collection>/ lists a *-database.sql.gz newer than the trigger.
  5. With the scheduler paused (bench --site <s> set-config pause_scheduler 1), the configure job’s preflight refuses and names it rather than reporting a configured edge.
  6. shc update <frappe-stack> -i webdav! leaves enabled = 0 on the Single, the collection intact, and a teardown message naming what remains.
  7. A deliberately ported origin (--var webdav.origin=https://cloud.example.com:443) makes the provision job refuse with the port named, not publish.

9.2 Phase 2: the things phase 1 knowingly does not do

Section titled “9.2 Phase 2: the things phase 1 knowingly does not do”
  • Per-consumer credentials on the deposit account, gated on an optional label, using the same occ user:auth-tokens:add the sibling socket uses (§4.3). Trigger: a second consumer.
  • Retention. §2.5: nothing prunes, ever. Options are a Nextcloud-side retention job (occ has no such command; it would be a crons: entry running a DAV sweep), a quota that simply fills and starts failing loudly, or an explicit refusal to manage it. RULING OWED §11.3.
  • external-webdav. The shim is what makes the stem’s name honest, and writing it is a vars.yaml plus a socket file with no jobs. It is not in phase 1 only because nothing needs it yet, but note the ratchet: scripts/arch-fitness.sh check 22’s external-shim-socket-stem has a ceiling of 0 and would be satisfied on the day it lands, since the stem already matches.
  • A restore path. Explicitly out of scope in both phases. bench restore from a WebDAV URL is a different verb with a different blast radius, and the migration doctrine (make migrate, never flatten) governs it.

Nextcloud → frappe of any kind. Per-user file spaces. Nextcloud External Storage pointed at SHC’s own restic repository (an S3 bucket is never a vApp, and adoption is an edge operation). Making this edge SHC’s primary backup, in any documentation, anywhere.


10. Remaining unknowns, each with the command that settles it

Section titled “10. Remaining unknowns, each with the command that settles it”

Ranked by what they would cost if the assumption is wrong.

#UnknownSettles withIf wrong
1Does a freshly occ user:add-ed account have a materialised DAV home before first login? (§4.2)occ user:add --password-from-env probe; curl -u probe:… -X PROPFIND -H 'Depth: 0' …/dav/files/probe/ -w '%{http_code}'; expect 207the provision needs a --group (which triggers Filesystem::init) or a warm-up request; a 404 here means every first deposit fails
2Does frappe.client.set_value satisfy a Single’s six reqd fields in one call, or does it need frappe.get_doc(...).save()? (§8.3)bench --site <s> execute frappe.client.set_value --kwargs "{…all six…}" then read backthe configure job needs a different write primitive; the whole job is otherwise unchanged
3Is the pinned image digest still the one the estate runs? (§0.3)docker image inspect nextcloud@sha256:58bc7333… vs docker pull nextcloud:34.0.2-apachethe occ and remote.php reads need redoing against the pin; nothing here is version-sensitive, so this is diligence rather than risk
4Does /remote.php/webdav (uid-free) behave as the authenticated principal’s root? (§3.1)curl -u u:p -X PROPFIND -H 'Depth: 0' …/remote.php/webdav/ -w '%{http_code}'only changes whether davPath can be made account-independent, a simplification, never a blocker
5Does nextcloud_integration install cleanly on a v15.117 bench and register its scheduler events?bench --site <s> install-app nextcloud_integration && bench --site <s> execute frappe.utils.scheduler.get_scheduler_eventsthe app’s four frappe imports are verified (§2.4) but the install has not been run; a v15 incompatibility elsewhere would surface here
6Does the app’s PUT survive an SHC ingress in the public posture? (§2.3)deposit once with vars.webdav.origin set to the public https originonly decides whether the public posture is documented as supported; the in-fabric default is unaffected

★ And the largest one, stated without hedging: none of this has been built or run. The upstream reads are solid (the URL-builder defects in §2.2 were reproduced, not inferred, and the occ semantics in §4.2 were read off the image), but no socket has been rendered, no plug bound, and no archive deposited. The first implementation pass will find things this document got wrong.


  1. The deposit account: dedicated user, or the existing admin grant? (§4) The recommendation is a dedicated non-admin account, because unlike the calendar bridge’s user enumeration there is a scoped surface here (a plain user’s own DAV home), so taking admin authority would be taking more than the capability needs. The counter-argument is real and should be heard: a synthetic account lands inside the user set the mailbox reconciler and the calendar bridge both enumerate, and nextcloud.socket.yaml already refused a service user for exactly that reason. If the ruling goes the other way, the socket publishes adminUser and the plug declares a label, and §4.1’s argument becomes a documented, accepted trade rather than a refusal.

  2. Does the teardown disable the deposit account? (§8.1) Reporting only is the safe default and matches the retained-cleanup channel’s whole purpose. Disabling stops future deposits from a detached consumer without destroying a single archive, and a shared account means a detach does not imply the account is unused. Recommendation: report only, and revisit when the per-consumer credential of §9.2 makes “this consumer’s access” a thing that can be revoked on its own.

  3. Retention. (§2.5, §9.2) Nothing prunes. The three answers are: let the quota fill and fail loudly (honest, and the failure email is already wired); a Nextcloud-side sweep (new machinery, and it deletes backups); or state in the socket that retention is the operator’s, and print the quota at every bind. Recommendation: the third now, the first as its consequence, and never the second without an explicit ruling, because a job that deletes archives is exactly the class the estate keeps getting hurt by.

  4. How many bench apps does the SHC frappe image carry, and who decides? (§8.4) This edge makes it three, one of them a dormant third-party pin at 0.0.1. That is a packaging policy question, not this socket’s to answer, but this socket is what forces it.

Not owed, because it is decided by measurement, not taste: the published origin carries no port and no path (§2.2), and webdav.socket.yaml declares service: nextcloud (§5.3). Both are constraints read off code, and a design that contradicts either does not work rather than works differently.