# Controller — LAN file sharing over SMB („Megosztás")

> **Code-verified feature doc.** Matches `felhom-controller` **v0.144.0** (R-7 slice 1) and the infra
> image **`gitea.dooplex.hu/admin/felhom-samba:1.0.0`**. Transport/discovery verdicts come from
> `documentation/audits/SPIKE-lan-discovery-2026-07-18.md` (R-6). Where this doc and the code
> disagree, the code wins — update this file.

## What the customer gets

The box behaves like a NAS on the home network. On **„Megosztás" → „Hálózati megosztás"** the customer
turns sharing on, sets ONE household SMB password, and exports folders. The box then appears in
Windows Explorer's *Network* view (and in Mac Finder) as `\\FELHOM`; opening a share and writing to it
works from any household device. Sharing is **LAN-only** — it is never exposed through the tunnel.

## Why it is NOT a catalog app

SMB ships as an **embedded controller feature** — the **fourth protected infra stack**
(traefik / cloudflared / filebrowser / **samba**). Three reasons, all structural:

1. **Host networking is mandatory.** The R-6 spike proved the default Docker bridge is categorically
   deaf to the LAN multicast that WSD and mDNS discovery need; only a container in the guest's own
   network namespace can send *and* receive it.
2. **Its config is a generated share list**, rendered into `smb.conf` — not a handful of env vars a
   catalog template could carry.
3. **Its share roots must ride the backup classification**, which catalog metadata cannot express for
   absolute, customer-chosen paths.

## The image (`felhom-samba:1.0.0`)

Built from `controller/infra-images/samba/` by `controller/scripts/build-samba-image.sh`. Pinned
alpine 3.21 (by digest) running **three** daemons under `tini`:

| Daemon | Port(s) | Why |
|---|---|---|
| `smbd` | 445 | the SMB/CIFS server itself |
| **`nmbd`** | 137/138 | **NetBIOS flat-name resolution** — without it the box is *visible* in Explorer but the double-click fails `0x80070035` (S4b of the spike: WSD hands Explorer an icon, not a name→IP mapping) |
| `wsdd` | 3702 / 5357 | WS-Discovery, so the box appears in Explorer's Network view at all |

The image is deliberately **dumb**: `/etc/samba/smb.conf` is bind-mounted READ-ONLY by the controller,
nothing is templated inside, and **no share name or password is ever baked in**. The passdb lives on
a named volume (`samba-passdb`) so the household password survives container recreation. Never
tagged `:latest`; the controller pins the exact tag in the compose it generates.

## Configuration model

Persisted in `settings.json` (`internal/settings/smb.go`):

- `smb: {enabled, server_name, user_set}` — `server_name` is the NetBIOS name (≤15 chars,
  letters/digits/hyphen/underscore; default `FELHOM`).
- `smb_shares: [{name, path, read_only, offsite, created_at}]` — the share registry.

> **The SMB password is never persisted.** Only the boolean `user_set` is stored. The secret is passed
> to `smbpasswd` on **STDIN** (never argv, which is world-readable via `/proc`), is never logged, and
> never appears in `smb.conf`, the compose file, or `settings.json`.

## Generated `smb.conf`

Global block (hardened, all controller-managed):

```
  server min protocol = SMB2      # no SMB1
  security = user                 # named auth only
  map to guest = never            # no anonymous access, ever
  disable netbios = no            # nmbd on → \\NAME resolves
  bind interfaces only = yes
  interfaces = lo eth0            # LAN + loopback ONLY, never the docker bridges
```

Each share adds a section with `force user`/`force group = felhom` (uid:gid **1000**), so files written
over SMB carry the same ownership the apps and both backup tiers expect:

```
[dokumentumok]
  path = /mnt/felhom-drives/hdd_1/shares/dokumentumok
  read only = no
  valid users = felhom
  force user = felhom
  force group = felhom
```

A read-only share gets `read only = yes` **and** a `:ro` bind in the compose file — defence in depth,
so a samba misconfiguration alone cannot make it writable.

## Lifecycle

`ensureSamba` runs inside `EnsureBaseStack` (boot + every health tick) after filebrowser, gated on
`smb.enabled` — the same conditional-deploy shape cloudflared uses. `ReconcileSamba` runs after every
share/settings mutation: re-render → atomic write (tmp + fsync + rename) → `compose up -d`.

- **Idempotent:** unchanged config plus a running container performs **zero** compose calls.
- **No password, no deploy:** with sharing on but no household password set, the stack stays
  undeployed and the UI blocks with „először adj meg jelszót". (Setting the password brings the stack
  up as part of that action — safe, because `security = user` + `map to guest = never` means nothing
  is reachable until the password lands.)
- **Dead mounts are never exported:** a share whose drive is disconnected or decommissioned is
  rendered ABSENT from `smb.conf` (publishing a missing mountpoint would show an empty share and let a
  write land on the underlying root instead of the drive). Its configuration is retained, and the UI
  row shows „A meghajtó nem elérhető."

### This feature never deletes customer data

There is no file-removal path in it at all. Disabling sharing is `compose down` (the passdb volume and
every shared folder are kept). Deleting a share is a **config-only** edit — the UI says so explicitly:
„A megosztás törölve — a mappa és a fájlok megmaradtak." The only directory creation is the guarded
new-share-folder create.

## Choosing what to share — the picker guard

Shares can be a **new folder** under `<storage>/shares/`, or **any existing folder**, with one
exception class: system data. Every customer-supplied path goes through `sharingResolvePath`:

1. must be **absolute**;
2. `EvalSymlinks` **before** the containment check — a symlink planted inside a storage root cannot
   point outside it;
3. must resolve inside a **registered, live** storage root (decommissioned roots are out);
4. must not be inside a deny-listed **system subtree** — `appdata/` (sharing a live app database
   writable over SMB is a corruption foot-gun), `backups/`, the legacy `felhom-data/` nest;
5. the **drive root itself** is refused (a whole drive is never shareable) — an exact-match rule, so
   ordinary user-data folders *under* it stay shareable;
6. must be a directory.

**Every refusal returns the same message** („Ez a mappa nem osztható meg.") so the picker can never be
used as an oracle for what exists outside the customer's storage.

The deny-list is **derived** from `stacks.ProtectedHDDPaths` (each entry is emitted only if that guard
already contains it), so it can only ever *shrink* relative to the delete guard — it can never drift
into a stale second source of truth. `media/` and `Dokumentumok/` are protected *there* as delete
targets but are customer data and remain shareable.

The new-folder flow uses a separate, strictly tighter check (`sharingResolveStorageRoot`) that accepts
**exactly** a registered live storage root — because there the root is the *parent*, not the share.

## Backup classification

`ClassifiedBinds("samba")` resolves from the shares registry instead of catalog metadata (samba has no
`.felhom.yml`, and its binds are absolute share paths):

| Per-share „Felhőmentés" | Class | Tiers |
|---|---|---|
| ON (default for new shares) | `mandatory` | offsite **and** tier-2 |
| OFF | `optional` | tier-2 only (never offsite) |

`smb.conf` and the passdb are config, not customer data, and are never classified.

## Backup EXECUTION — the sibling shares source (R-7b, controller v0.145.0)

The classification above is now *executed*. It did not get there through `ClassifiedBinds` — the
engines stayed recovery-unit shaped and Model B′ deliberately left every per-app path byte-identical.
Instead `internal/backup` runs a **sibling shares source** off the same registry:

| Tier | Entry point | What it writes |
|---|---|---|
| 2 (cross-drive) | `RunSharesTier2`, after the per-stack loop in the same run | `backups/secondary/_shares/<sourceDriveKey>/<share>` per source drive, `_payload/`, `.felhom-tier2-layout` written **LAST** |
| 3 (offsite) | `runOffboxSharesLeg`, after the per-app loop and **before** retention | ONE `restic backup --tag felhom-offbox --tag _shares` = payload dir + every MANDATORY share |
| restore | „Megosztások" on `/backups/restore` | scratch → missing-only merge, each destination prefix-asserted against LIVE storage roots |

**The payload is the point.** `_shares-manifest.json` carries the share *definitions* (sorted →
byte-deterministic, so an unchanged registry gives the mirror nothing to rewrite) and `passdb.tar`
carries the household credential, best-effort. Without it a restore hands the customer their files
back and an empty „Megosztás" page. The credential copy is **secret-bearing**: 0600, encrypted inside
restic, never logged at INFO and never in a report or a committed file.

**Degradation contract.** A quota-blocked offsite push falls back to the **manifest only, never to
nothing** — definitions protection must not regress because the files stopped fitting.

**Restore semantics.** Files merge missing-only (a live file is never overwritten). Definitions merge
**existing-wins**: a restore must never silently flip a live share's read-only or „Felhőmentés"
setting, and anything skipped is named in the flash. Then `ReconcileSamba` re-renders `smb.conf`, then
the credential goes back into the named volume.

**`_shares` is a reserved key** (restic tag, dest root, status record). `ValidateSMBShareName` refuses
a leading underscore — note this was a REAL gap, not a formality: `nbNameRe` begins with
`[A-Za-z0-9_]`, so „_shares" was previously an accepted share name. The key never reaches a customer
surface; `backup.DisplayStackName` maps it to „Megosztások" at the notification and prose boundaries,
while the persisted set, the tag and the paths keep the raw key.

> **Live-validation status (2026-07-18): FULLY PROVEN-LIVE.** Tier-2 leg via the real
> `/api/backup/tier2` endpoint (tree + marker + payload, mirrored file md5-identical, payload 0600
> preserved). Offsite leg: snapshots `e0b9d723` (Viktor's manual run) and `4e2b15ec`, each tagged
> `felhom-offbox,_shares` and carrying the payload dir (`_shares-manifest.json` + `passdb.tar`, both
> 0600) alongside both share folders with uid 1000 preserved. Restore round-trip: a deleted probe file
> came back byte-identical and a deleted share DEFINITION came back with its original flags, while the
> two pre-existing files were NOT overwritten and `filmek` was reported *kept* — the missing-only and
> existing-wins contracts proven on live data. Samba liveness: hub-accepted `health_critical`.
> Remaining human leg: SMB positive auth with the real household password, which is never persisted.

## Operator notes

- samba is protected in **code** (`config.alwaysProtectedStacks`), because `cfg.Stacks.Protected` comes
  from the golden-generated `controller.yaml` and predates the feature. **Since v0.145.0 (R-7b) it is
  also monitored for liveness:** `monitor.EffectiveProtected` takes the SMB settings and adds the
  container `infra.SambaContainerName` exactly while sharing is ON, so a dead sharing service raises
  the standard protected-container issue → `health_critical` → alert → Hungarian degradation e-mail,
  while a box that never enabled sharing stays quiet (both directions unit-tested and red-proofed).
  Note the CONTAINER name (`felhom-samba`) is deliberately not the stack name (`samba`) — the health
  check docker-inspects container names. PROVEN-LIVE 2026-07-18: stopping the container produced
  `Protected container not running: felhom-samba`, status `fail`, and a hub-accepted `health_critical`
  event; the next tick's `EnsureBaseStack` self-healed it.
- Discovery depends on the household LAN. The R-6 spike's §7d caveat applies: a customer network with
  IGMP snooping enabled and **no querier** could prune the discovery multicast, and a BYO topology may
  put the guest on a bridge with no L2 path to the household LAN. The page carries an honest hint that
  the device list can lag while `\\NÉV` always works.
- The customer authenticates as user **`felhom`** with the household password.

## Not in slice 1 (→ slice 2)

avahi / `.local` name publishing for modern + Apple clients; curated app-folder presets (one-click
paperless `consume/`); per-share users and guest access; a recycle bin. DLNA is a separate item (R-8).