refactor(oidc): prep. support of Open Cloud Mesh

add federation kind (OCM, OIDC, MagicLink) rename oidc_provider into federation_issuer rename oidc_subject into federation_subject
2026-08-08 15:10:23 +02:00
parent 521040521d
commit 10a8dd7d8b
13 changed files with 1254 additions and 127 deletions
@@ -0,0 +1,516 @@
+# Open Cloud Mesh (OCM) — Federated Sharing
+
+Federate file-sharing with Nextcloud, ownCloud, Reva/OCIS, Seafile, and any
+other OCM 1.1+ speaker. Track the design decisions here before code lands.
+
+## Identity & auth model — DECIDED
+
+OCM-federated recipients live as **shadow rows in `auth.users`** with:
+
+- `is_external = true`
+- `password_hash = NULL` (enforced by existing `users_external_no_storage`
+  CHECK constraint)
+- `email = federated-address` (e.g. `bob@nextcloud.example.com`)
+- Federation columns (see "Schema rename — PRE-REQ" below for the
+  migration path that turns today's OIDC-specific columns into these):
+  - `federation_kind ∈ {NULL, 'magic_link', 'ocm', 'oidc'}` — distinguishes
+    the trust chain that owns this identity. NULL for internal users.
+  - `federation_issuer` — **THE AUTHORITY** that mints the subject id.
+    NOT a display name. The full identity per federation kind is
+    `(federation_issuer, federation_subject)`; the issuer is what makes
+    a subject id meaningful — two different IdPs can independently mint
+    `sub=1234` for two completely different people.
+    - `oidc` — the `iss` claim from the id_token (also
+      `discovery.issuer`), e.g.
+      `https://sso.example.com/realms/main`. Immutable per
+      spec (RFC 7519 §4.1.1).
+    - `ocm` — the peer domain, e.g. `nextcloud.example.com`. The
+      peer's domain IS the authority for its federated identities in
+      OCM's model.
+    - `magic_link` — NULL (identity is the local `email`, no external
+      authority involved).
+    - **Fixes an existing bug.** Today `oidc_provider` stores the
+      human-readable `OXICLOUD_OIDC_PROVIDER_NAME` label (e.g. "SSO",
+      "MockSSO"), not the issuer URL. Consequences of the current
+      shape:
+      1. Admin renaming `OXICLOUD_OIDC_PROVIDER_NAME` silently
+         orphans every existing OIDC user — new lookups key on the
+         new label, stored rows have the old one.
+      2. BCL revocation (`revoke_user_sessions_by_oidc_subject`)
+         keys on the label; same rename → BCL notifications from the
+         IdP match no one. Silent security regression — users
+         thought-kicked stay logged in.
+      3. Multi-IdP futures (multi-realm, multi-tenant) would suffer
+         cross-issuer subject collision if two IdPs share a display
+         name.
+    - Display name becomes a separate concern — either derived from a
+      `peer_configs.issuer → display_name` lookup, or stored alongside
+      as a denormalized `federation_display_name` column (admin-
+      editable, no identity impact). Not part of the identity key.
+  - `federation_subject` — the remote id string. Stability:
+    - `oidc` — the `sub` claim, issuer-assigned, MUST NOT change per spec
+      (RFC 7519 §4.1.2, OIDC Core §5.4). Email can change on the IdP
+      side with no impact on this row.
+    - `ocm` — the full federated address (`bob@nextcloud.example.com`).
+      OCM 1.1 does NOT define a separate stable subject id; the address
+      IS the identity. If a peer renames a user, we see a new address
+      and create a new shadow row. Grants against the old row are
+      orphaned until admin intervention. This is a protocol
+      limitation — some peers ship extensions (Nextcloud Global Site
+      Selector, ScienceMesh/Reva `opaqueUserId`) but they aren't in
+      base OCM. Treat `federation_subject` as opaque; if a future OCM
+      version adds a stable id, swap the value in without schema change.
+    - `magic_link` — NULL (magic-link externals don't carry a federation
+      subject; their identity is the local `email` column).
+  - Composite UNIQUE index `(federation_kind, federation_issuer, federation_subject)`
+    WHERE `federation_kind IS NOT NULL`.
+- `storage_quota_bytes = 0`, no home folder provisioned
+
+**Grants stay `subject_type = 'user'` on `storage.role_grants`.** No new
+subject-type variant. The team's earlier refactor (2026-07-30) removing
+`'external'` from the CHECK constraint is the precedent — external is a flag
+on the user row, not a subject type.
+
+**AuthZ engine unchanged.** Middleware for OCM WebDAV resolves sharedSecret →
+`ocm.outbound_shares.recipient_user_id` (the shadow row), sets `CurrentUserId`
+to that, and the existing `authz.require(subject, resource, permission)` runs
+identically for local + federated subjects.
+
+## Schema rename — PRE-REQ (ships before ANY OCM code)
+
+Today's `auth.users.oidc_provider` / `oidc_subject` are semantically identical
+to the generic `federation_issuer` / `federation_subject` above. Keeping both
+would be drift risk. Rename first, then start OCM work on top of the clean
+shape.
+
+```sql
+ALTER TABLE auth.users RENAME COLUMN oidc_provider TO federation_issuer;
+ALTER TABLE auth.users RENAME COLUMN oidc_subject  TO federation_subject;
+ALTER TABLE auth.users ADD  COLUMN federation_kind TEXT
+    CHECK (federation_kind IN ('magic_link', 'ocm', 'oidc'));
+
+-- Backfill kind: rows that had oidc_provider set were all OIDC-linked.
+UPDATE auth.users SET federation_kind = 'oidc'
+    WHERE federation_issuer IS NOT NULL;
+
+-- Swap the anti-duplicate index.
+DROP   INDEX idx_users_oidc;
+CREATE UNIQUE INDEX idx_users_federation
+    ON auth.users(federation_kind, federation_issuer, federation_subject)
+    WHERE federation_kind IS NOT NULL;
+```
+
+**Value migration is more than a rename** — today's stored values in the
+renamed `federation_issuer` column are DISPLAY LABELS (e.g. `'MockSSO'`,
+`'MyIdP'`), not issuer URLs. Rewriting them to real issuer URLs
+touches every existing OIDC row and can't happen in one atomic step without
+losing rollback ability. Phase it:
+
+### Rename PR — Phase A (schema)
+- Add columns (`federation_kind`, `federation_issuer` renamed from
+  `oidc_provider`, `federation_subject` renamed from `oidc_subject`) —
+  the SQL block above.
+- Application code DUAL-WRITES on OIDC login: still writes the display
+  label to `federation_issuer` (unchanged semantics) AND stamps
+  `federation_kind = 'oidc'`. Reads unchanged.
+- Ships safely as a pure rename + kind-backfill. Rollback = drop the
+  `federation_kind` column; the renamed columns keep working with the
+  old code because their VALUES haven't changed.
+
+### Rename PR — Phase B (progressive lazy rebind on OIDC login)
+
+**Simplification** — no explicit backfill CLI needed. The id_token
+carries the true `iss` claim on every OIDC login, so the migration
+does itself organically:
+
+- On every successful OIDC login: if the user's stored
+  `federation_issuer` does not equal the id_token's `iss`, UPDATE it
+  (with an audit line `event="federation.issuer_rebound"`,
+  `reason="lazy_backfill"`). First login post-upgrade heals the row.
+- Users who never log in stay on the legacy label — but they also
+  can't do anything (no login → no action), so the stale value is
+  harmless. It appears only in admin listings, where a "legacy label
+  needs rebind" badge could surface if we care.
+- Contradiction guard: if the observed `iss` is DIFFERENT from the
+  stored issuer AND the stored issuer is already a valid URL (not a
+  display label), that's a genuine identity change — refuse the login
+  with an audit event and admin alert. Preserves "identity change is
+  admin-mediated." Heuristic for label vs URL: starts with `http://`
+  or `https://` and contains `/`.
+- Same lazy-rebind logic covers BCL: if a BCL notification's `iss`
+  matches a user's `federation_subject` but issuer differs, we can
+  either rebind (safer bet: same peer just told us their true issuer)
+  or refuse and audit. Recommend refuse-and-audit, since BCL is
+  server-to-server and less user-driven.
+
+**CLI subcommand shape (optional, ships later if needed)** — lives
+under `oxicloud-cli federation …` (see `src/bin/oxicloud-cli.rs` for
+the domain/action pattern; add `federation` module alongside
+`opaque`). Two subcommands worth having if operators want proactive
+control:
+
+- `federation status` — show counts of users by `federation_kind` and
+  how many still hold display-label-shaped `federation_issuer` values.
+- `federation remap-issuer --from-label X --to-issuer https://...` —
+  bulk-update the users still holding a specific legacy label, for
+  operators who want to close the migration without waiting for
+  every user to log in.
+
+**All user-identifier arguments accept EITHER username OR user UUID.**
+Not all users have a username (email-only signups per PR-18 leave it
+NULL); the CLI must handle both, resolving via
+`SELECT id FROM auth.users WHERE username = $1 OR id::text = $1`.
+Applies to any subcommand that takes a user reference.
+
+- New admin CLI or boot-time task: for each row where
+  `federation_kind = 'oidc'`, try to derive the true issuer URL:
+  - **Single-IdP deployment** (typical): if the current OIDC config's
+    `issuer_url` is set AND no other candidate exists, UPDATE all rows
+    to that issuer. One-line log per row updated.
+  - **Multi-value case** (deployment has renamed
+    `OXICLOUD_OIDC_PROVIDER_NAME` mid-life, so the same physical IdP
+    has rows with different labels): auto-backfill would smear all
+    labels into the SAME issuer — WRONG for rows that predate the
+    label swap. **Refuse to auto-backfill**; emit a boot audit warning
+    listing the distinct current values + affected user_ids; require
+    operator to pick a mapping via CLI (`oxicloud federation
+    remap-issuer --from-label X --to-issuer https://…`) or accept
+    the current-config issuer for all rows via
+    `--all-legacy-labels`.
+  - **Genuine multi-IdP** (rare today, forward-looking): fail loud;
+    no automatic mapping is safe. Manual mapping per label.
+- Log each mapping decision to `audit` for post-hoc traceability.
+- Ship after Phase A has been in production long enough to prove
+  stable (one release cycle at minimum).
+
+### Rename PR — Phase C (read switch + lazy rebind)
+- Application code reads anti-duplicate lookups AND BCL revocation
+  keying on `(federation_kind, federation_issuer, federation_subject)`.
+- On EVERY successful OIDC login: if the row's current
+  `federation_issuer` value doesn't equal the id_token's `iss` claim,
+  UPDATE it (with an audit line). This catches rows Phase B couldn't
+  resolve automatically — the first login after rollout self-heals.
+- Dual-write continues (kind + issuer both stamped from id_token now).
+- Hard failure mode to watch for: if the `iss` on the id_token
+  contradicts a Phase-B-backfilled value for existing users, we've
+  either (a) misconfigured the IdP, or (b) the IdP is a completely
+  different one than we backfilled to. Refuse the login with an audit
+  event and admin alert rather than silently rebind — preserves the
+  principle "identity change is admin-mediated".
+
+### Rename PR — Phase D (drop legacy compatibility)
+- Precondition check: no rows remain with a `federation_issuer` value
+  that looks like a display label (heuristic: doesn't start with
+  `http://` or `https://`, doesn't contain `/`).
+- Remove any dead code paths that assumed display-label semantics.
+- No column drop needed — the columns are already renamed. This phase
+  is code-only.
+- Ships when telemetry from Phase C shows zero unresolved
+  federation_issuer values across the fleet.
+
+Total: rename in one release cycle, value backfill in the next, read
+switch after that, cleanup at leisure. Each phase reversible. Operator
+warnings surface the exceptional cases (multi-label, multi-IdP) so
+they don't get silent-defaulted into a broken state.
+
+Rust-side rename (~15-20 sites, mechanical):
+- `User` entity fields (`oidc_provider` → `federation_issuer` etc.)
+- `UserPgRepository` SQL statements
+- `OidcIdClaims → User` mapping in `auth_application_service` (sets
+  `federation_kind = 'oidc'`)
+- `admin_settings_service`'s env-override table
+- Any DTOs that leaked `oidc_provider` externally — check `UserDto` before
+  the migration in case FE reads the field
+- Tests
+
+Why rename rather than coexist:
+- `oidc_provider` is a misleading name anyway — a value like
+  `MyIdP` isn't a "provider" (that's a category), it's the IdP's
+  identity/name. `federation_issuer` reads more truthfully.
+- Adding OCM alongside without renaming forces every future query that asks
+  "is this user externally-owned?" to check two column pairs. One canonical
+  shape is cheaper.
+
+The rename can ship as an independent PR before OCM work starts. Backfilling
+`kind = 'oidc'` for existing rows is monotone (no NULL flips), so the
+migration is reversible if we need to abort.
+
+## Magic-link on federated addresses — DECIDED
+
+Default: **`federation_kind='ocm'` users CANNOT use magic-link login.**
+Same rule shape as the existing OIDC-master rule
+(`feedback_oidc_master_no_magic_link_bypass`).
+
+Enforcement in `is_magic_link_login_allowed_for(&user)`:
+
+```
+if user.federation_kind == Some(FederationKind::Ocm) {
+    return false;  // audit: reason="ocm_federated"
+}
+```
+
+Rationale:
+- OCM's identity boundary is the remote peer's authentication (which may
+  enforce MFA, geo-fence, hardware keys). Magic-link would downgrade that to
+  mailbox-strength.
+- Federation revocation on the remote side (peer disables bob) should NOT
+  leave bob with a working login on our side via his mailbox.
+- Same anti-enumeration shape as `oidc_user` rejection — 404 to the caller,
+  audit line internally.
+
+### Deferred opt-in: `allow_magic_link_for_ocm_federated`
+
+Some deployments will want unified UX (federated invite doubles as a browser
+account). Ship as an additive policy on `OXICLOUD_AUTH_POLICIES`:
+
+```
+OXICLOUD_AUTH_POLICIES=allow_magic_link_for_ocm_federated
+```
+
+Same shape as `permit_magic_link_for_password_users` — off by default,
+operators who enable it accept the auth-boundary trade-off. Document alongside
+the shared-computer / weakened-boundary caveat.
+
+**Not implemented in the initial OCM ship.** Add when a deployment actually
+asks for it.
+
+## Reverse case: address already exists as magic-link external
+
+If `bob@example.com` is already in our DB as a magic-link external (a local
+user invited him last month) AND a peer sends us an OCM share addressed to
+`bob@example.com`, do NOT upgrade in place. Create a separate shadow row
+with `federation_kind='ocm'`. Different trust chains, different identities.
+The composite UNIQUE index on `(federation_kind, federation_issuer,
+federation_subject)` allows the two rows to coexist.
+
+Consequence: magic-link bob CAN log in; OCM bob CANNOT. Same address, two
+accounts, two postures. Honest about the different trust semantics.
+
+## New DB shape
+
+```
+ocm.trusted_peers   -- allowlist of federation partners
+ocm.outbound_shares -- shares WE created for remote users (with acceptance state)
+ocm.inbound_shares  -- shares OTHER servers created for our users (with acceptance state)
+ocm.notifications   -- wire-level OCM notifications (retry queue + dedup + forensic audit)
+```
+
+### `ocm.notifications` in detail
+
+**Not to be confused with acceptance state.** When a user clicks
+Accept/Decline on a pending invitation, that mutates
+`ocm.inbound_shares.state` — the user's decision lives there. This
+table stores the *wire message* we then send to the peer telling them
+"our user accepted." The two are logically distinct: acceptance is
+share-scoped workflow state, notifications are transport-layer events.
+Future readers: don't conflate.
+
+Given that, `ocm.notifications` serves FOUR overlapping purposes.
+Collapsing them into one table (instead of parallel queue / dedup /
+audit tables) avoids drift.
+
+**1. Retry queue for outbound.** OCM 1.1 requires exponential-backoff
+retry when the peer's `POST /notifications` fails. Rows with
+`direction='outbound' AND processing_result='pending' AND
+next_retry_at <= now()` are what a background worker picks up.
+
+**2. Idempotency / dedup for inbound.** Peers may resend after network
+hiccups. `UNIQUE(peer_domain, remote_notification_id)` short-circuits.
+
+**3. Debugging.** "Why did that share disappear?" — grep by
+`related_share_id`. Payload preserved verbatim as JSONB.
+
+**4. Security audit.** Federated state transitions cross trust
+boundaries; every one is auditable, joinable to peer domain + share.
+
+Sketch:
+
+```sql
+CREATE TYPE ocm.notification_direction AS ENUM ('inbound', 'outbound');
+CREATE TYPE ocm.notification_kind AS ENUM (
+    'share_accepted', 'share_declined', 'share_revoked',
+    'share_unshared', 'user_removed', 'other'
+);
+CREATE TYPE ocm.notification_result AS ENUM (
+    'pending', 'success', 'failed', 'ignored'
+);
+
+CREATE TABLE ocm.notifications (
+    id                     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    direction              ocm.notification_direction NOT NULL,
+    peer_domain            TEXT NOT NULL,
+    related_share_kind     TEXT CHECK (related_share_kind IN ('inbound','outbound')),
+    related_share_id       UUID,        -- points at inbound_shares.id OR
+                                        -- outbound_shares.id; typed union
+                                        -- isn't natural in Postgres so no
+                                        -- hard FK — verify at insert
+    kind                   ocm.notification_kind NOT NULL,
+    payload                JSONB NOT NULL,
+    remote_notification_id TEXT,
+    created_at             TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    processed_at           TIMESTAMPTZ,
+    processing_result      ocm.notification_result NOT NULL DEFAULT 'pending',
+    attempt_count          INTEGER NOT NULL DEFAULT 0,
+    next_retry_at          TIMESTAMPTZ, -- outbound only
+    error_message          TEXT,
+    UNIQUE (peer_domain, remote_notification_id)
+);
+
+CREATE INDEX idx_ocm_notif_related
+    ON ocm.notifications(related_share_id, related_share_kind);
+CREATE INDEX idx_ocm_notif_retry
+    ON ocm.notifications(next_retry_at)
+    WHERE direction = 'outbound' AND processing_result = 'pending';
+CREATE INDEX idx_ocm_notif_peer
+    ON ocm.notifications(peer_domain, created_at DESC);
+```
+
+**Retry policy** — attempt 1 immediate; 2-5 with exponential backoff
+(30s, 2m, 10m, 1h); after attempt 5, mark `failed` and emit
+`event="ocm.notification_delivery_gave_up"` with admin alert.
+Configurable via `OXICLOUD_OCM_NOTIFICATION_MAX_ATTEMPTS` (default 5).
+
+**Retention** — 90 days default, purged by a nightly consistency-job
+handler (`notifications_cleanup`), fits the existing recovery-jobs
+pattern. `failed` rows kept indefinitely until admin resolution
+(paper trail). Configurable via
+`OXICLOUD_OCM_NOTIFICATION_RETENTION_DAYS`.
+
+**Inbound security invariants** — verify BEFORE mutating any state:
+
+- Peer domain matches the peer that owns the referenced share
+  (`peer_mismatch` → mark `ignored`, audit).
+- `related_share_id` points at an existing share in the correct table
+  (`unknown_share` → `ignored`).
+- Notification kind is compatible with current share state
+  (`state_conflict` → `ignored`, e.g. accept on an already-declined
+  share).
+
+Each rejection emits an `event="ocm.notification_rejected"` audit line
+with a stable `reason=` field (`peer_mismatch | unknown_share |
+state_conflict | duplicate`) — same anti-drift discipline as other
+structured audit events, per `feedback_enum_over_string_literals_in_logs`.
+
+Plus `auth.users` new columns above.
+
+Plus `storage.resource_kind` extension for a `RemoteShare` resource type
+(pointing at `ocm.inbound_shares.id`), so accepting an inbound share is a
+regular grant row from the accepting user to the RemoteShare resource.
+
+## Invitation workflow — where accept/decline lives
+
+Local grants have no accept/decline concept — the grant IS the access.
+OCM introduces one because the protocol is push-driven (peer POSTs a
+share, our user decides whether to surface it). Solved WITHOUT adding
+state to `role_grants`:
+
+**Inbound shares (peer → us):**
+- `POST /ocm/shares` creates an `ocm.inbound_shares` row (pending). NO
+  role_grant created yet.
+- User sees pending invitation in `/shared-with-me` → `Federated` tab
+  (new), plus a badge on AppShell.
+- **Accept** → insert `role_grants` row (subject = local user, resource
+  = a new `RemoteShareResource` entry, permission = as offered), POST
+  accept notification to peer, mark `ocm.inbound_shares.accepted_at`.
+- **Decline** → no grant created; POST decline notification, mark
+  `ocm.inbound_shares.declined_at`. Row kept for audit.
+- Modal prompt on next login if pending count changed since last login.
+
+**Outbound shares (us → peer):**
+- Grant is created immediately in `role_grants` (subject = shadow user
+  for the federated recipient). AuthZ from OUR side is active the
+  moment the OCM POST succeeds — remote user CAN consume via WebDAV.
+- `ocm.outbound_shares` tracks delivery + acceptance state
+  (`delivering | delivered | accepted | declined_by_recipient |
+  undeliverable | revoked`), surfaced in `/shared` (outgoing view) as
+  a status column.
+- Share dialog recognizes `user@remote-domain` and shows a channel
+  badge on the resolved recipient (see
+  [federated-login.md § Same discovery layer serves invitation](./federated-login.md)).
+- Peer sends decline notification → auto-revoke the local grant
+  (recipient said no, keeping access is pointless). Configurable
+  behaviour deferred.
+
+**ReBAC extensions needed** (all local to the OCM code path, no engine
+churn):
+- New `resource_type = 'remote_share'` on `role_grants`, resource_id
+  pointing to `ocm.inbound_shares.id`. AuthZ dispatches to a
+  WebDAV-proxy handler for this type.
+- `ocm.inbound_shares.state` and `ocm.outbound_shares.state` columns
+  hold acceptance metadata. `role_grants` stays state-free.
+- OCM notification handler translates peer messages into local state
+  transitions (create/delete grant, update state column).
+
+## Future — merge with a generic grant-request workflow
+
+`ocm.inbound_shares.state` is a purpose-specific state machine for the
+MVP. If OxiCloud later gains a local pending-approval workflow (Alice
+asks Bob for Read on his folder; Bob approves) — a real
+enterprise-features ask — the natural refactor is to extract a shared
+workflow spine:
+
+- New table `storage.grant_requests` with
+  `(subject, resource, requested_permission, approval_authority, state,
+  decided_at, decided_by)`. Approval_authority distinguishes who holds
+  decide-power: `owner` (local approval), `recipient` (OCM inbound
+  accept, magic-link redeem), `admin` (policy gate).
+- `ocm.inbound_shares` keeps its federation-specific columns
+  (peer_domain, remote WebDAV URL, sharedSecret) and gains a
+  `grant_request_id` FK. Accept = flip request to `approved` + create
+  `role_grant`. Decline = flip to `rejected`.
+- `magic_link_tokens` with `resource_kind ≠ NULL` (invitation-purpose
+  tokens) gets the same FK. Redeem = flip to `approved` + create
+  `role_grant`.
+- **`role_grants` stays approved-only.** Hot AuthZ path doesn't gain a
+  state filter — no regression on read paths.
+
+**NOT** a merge of the tables themselves — collapsing OCM /
+magic-link / local-request into `role_grants` with a state column
+would leak state-machine logic into every AuthZ check. The merge is at
+the ABSTRACTION level: three flavors of "prospective grant" today
+(magic-link invite, OCM inbound, hypothetical local request) share ONE
+workflow table; channel-specific data stays in satellites.
+
+Migration is additive and non-breaking: add tables + FK columns,
+backfill existing rows as synthetic `approved` requests for audit
+continuity, refactor callers one at a time. No ReBAC engine change.
+
+Not urgent — the OCM MVP works fine without it. Recorded so the
+option isn't forgotten if local approval workflow ever gets requested.
+
+## Phasing (rough)
+
+1. **Phase 0** — Discovery (`/ocm-provider`) + inbound receive + FE listing
+   of received shares (metadata only, no consumption yet). ~1 week.
+2. **Phase 1** — Consume remote shares (server-side WebDAV proxy). ~1-2 weeks.
+   Needs a WebDAV client — none exists in the tree today.
+3. **Phase 2** — Outbound sharing (share dialog recognizes `user@remote`).
+   ~3-5 days.
+4. **Phase 3** — OCM 2.0 invite handshake (ScienceMesh trust flow). ~1 week.
+5. **Phase 4** — Address book / federated-contact registry. ~1 week.
+
+## Open design questions (not yet decided)
+
+- **Trust model** — open federation vs allowlisted peers? Recommend
+  allowlist-by-default (safer for self-hosted).
+- **Recipient resolution rule** — `username@LOCAL_DOMAIN` vs `email` match?
+  Recommend username-based (matches Nextcloud, deterministic).
+- **Quota accounting** — do consumed remote shares count against the
+  recipient's `storage_quota_bytes`? Recommend no (remote storage is remote).
+- **Notification authenticity** — bind every OCM notification to its
+  `inbound_share.id`, refuse if peer domain doesn't match the domain we
+  recorded at share creation.
+- **Group grants** — local group containing OCM-federated user is weird.
+  Semantically fine but the share dialog should probably discourage it.
+
+## Interop targets
+
+- Nextcloud in Docker as the primary peer (both directions).
+- OCIS/Reva as the CS3-blessed reference behaviour.
+- SciMesh integration tests once Phase 3 is in.
+
+## References
+
+- OCM 1.1 spec: <https://cs3org.github.io/OCM-API/>
+- Nextcloud OCM docs (implementation quirks): <https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/federated_cloud_sharing.html>
+- Reva (Go reference impl): <https://github.com/cs3org/reva>