Add Rails backend: accounts via magic link, server documents, sharing

The app becomes a Rails 8 application; the Vue frontend moves to
app/frontend and is served through vite_rails.

- Without an account documents stay in the browser (IndexedDB). Sign-in
  is by magic link or the 6-digit code from the same mail; afterwards
  local documents can be uploaded into the account.
- Server documents (/d/<id>) with versioned saves and a single-editor
  lock per browser tab; others see them read-only and follow by polling.
- Sharing via link (works without an account) and via e-mail invitation,
  roles viewer/editor; the owner manages links and people.
- Store gains a read-only mode that blocks all content changes.
- Solid Queue, Cache and Cable share the one PostgreSQL database.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app/controllers/api/auth_controller.rb

@@ -0,0 +1,37 @@
+module Api
+  class AuthController < BaseController
+    rate_limit to: 20, within: 1.hour, only: :magic_link, with: -> { too_many }
+    rate_limit to: 30, within: 15.minutes, only: :code, with: -> { too_many }
+
+    # POST /api/auth/magic_link { email, return_to }
+    # Always the same answer, so it can't be used to find out who has an account.
+    def magic_link
+      email = params.require(:email).to_s
+      unless MagicLink.throttled?(email)
+        link = MagicLink.issue!(email:, return_to: params[:return_to])
+        AuthMailer.magic_link(link, link.token, link.code).deliver_later
+      end
+      render json: { ok: true }
+    rescue ActiveRecord::RecordInvalid
+      render json: { error: "invalid_email" }, status: :unprocessable_entity
+    end
+
+    # POST /api/auth/code { email, code } -- the 6-digit code from the mail
+    def code
+      link = MagicLink.find_by_code(params.require(:email), params.require(:code))
+      return render(json: { error: "invalid_code" }, status: :unprocessable_entity) unless link
+      start_session_for(link.redeem!)
+      render json: { user: Current.user.as_json, redirect: link.destination }
+    end
+
+    # DELETE /api/auth/session
+    def logout
+      terminate_session
+      render json: { ok: true }
+    end
+
+    private
+
+    def too_many = render(json: { error: "rate_limited" }, status: :too_many_requests)
+  end
+end

app/controllers/api/base_controller.rb

@@ -0,0 +1,28 @@
+module Api
+  class BaseController < ApplicationController
+    # the app sends the CSRF token from the page's meta tag as X-CSRF-Token
+    protect_from_forgery with: :exception
+
+    rescue_from ActiveRecord::RecordNotFound do
+      render json: { error: "not_found" }, status: :not_found
+    end
+    rescue_from ActiveRecord::RecordInvalid do |e|
+      render json: { error: "invalid", messages: e.record.errors.full_messages }, status: :unprocessable_entity
+    end
+    rescue_from ActionController::InvalidAuthenticityToken do
+      render json: { error: "csrf" }, status: :unprocessable_entity
+    end
+
+    private
+
+    # a share link token, for visitors (with or without account) who got the link
+    def share_token = request.headers["X-Share-Token"].presence
+
+    # identifies the lock holder: one browser tab
+    def client_id = request.headers["X-Client-Id"].to_s[0, 64].presence || "anon"
+
+    def lock_holder = "#{Current.user&.id || 'anon'}:#{client_id}"
+
+    def holder_name = Current.user&.name || "Jemand mit dem Link"
+  end
+end

app/controllers/api/document_locks_controller.rb

@@ -0,0 +1,29 @@
+module Api
+  # The edit lock of a server document: one browser tab edits at a time,
+  # everyone else sees the document read-only until the lock is released or
+  # expires (Document::LOCK_TTL without a heartbeat).
+  class DocumentLocksController < BaseController
+    before_action :load_document
+
+    # POST /api/documents/:id/lock -- take or refresh (heartbeat)
+    def create
+      return render(json: { lock: { mine: false, holder_name: nil } }) unless Document.role_at_least?(@role, :editor)
+      mine = @doc.acquire_lock!(lock_holder, holder_name)
+      render json: { lock: { mine:, holder_name: (@doc.lock_holder_name unless mine) } }
+    end
+
+    # DELETE /api/documents/:id/lock
+    def destroy
+      @doc.release_lock!(lock_holder)
+      head :no_content
+    end
+
+    private
+
+    def load_document
+      @doc = Document.find(params[:document_id])
+      @role = @doc.role_for(user: Current.user, token: share_token)
+      raise ActiveRecord::RecordNotFound unless @role
+    end
+  end
+end

app/controllers/api/documents_controller.rb

@@ -0,0 +1,87 @@
+module Api
+  # Server documents. Listing and creating need an account; reading and
+  # writing a single document also work with just a share link token.
+  class DocumentsController < BaseController
+    before_action :require_authentication, only: %i[index create]
+    before_action :load_document, except: %i[index create]
+
+    # GET /api/documents -- owned + shared with me
+    def index
+      user = Current.user
+      memberships = user.document_memberships.index_by(&:document_id)
+      docs = user.accessible_documents.includes(:owner, :updated_by).order(content_updated_at: :desc)
+      render json: {
+        documents: docs.map { |d| d.meta_json(role: d.owner_id == user.id ? :owner : memberships[d.id]&.role) }
+      }
+    end
+
+    # POST /api/documents { title, content } -- also used to upload a local document
+    def create
+      doc = Current.user.owned_documents.create!(
+        title: params.require(:title), content: content_param, updated_by: Current.user
+      )
+      render json: { document: doc.meta_json(role: :owner) }, status: :created
+    end
+
+    # GET /api/documents/:id[?known_version=n]
+    # With known_version: just the metadata when nothing changed since.
+    def show
+      touch_membership
+      meta = @doc.meta_json(role: @role).merge(lock: @doc.lock_info(lock_holder))
+      if params[:known_version].present? && params[:known_version].to_i == @doc.version
+        render json: { document: meta, unchanged: true }
+      else
+        render json: { document: meta.merge(content: @doc.content) }
+      end
+    end
+
+    # PATCH /api/documents/:id { title } and/or { content, base_version }
+    def update
+      return forbidden unless Document.role_at_least?(@role, :editor)
+      if params.key?(:content)
+        return render(json: { error: "locked", holder_name: @doc.lock_holder_name }, status: :locked) if @doc.locked_by_other?(lock_holder)
+        @doc.with_lock do
+          if params.require(:base_version).to_i != @doc.version
+            return render(json: { error: "conflict", version: @doc.version }, status: :conflict)
+          end
+          @doc.update!(content: content_param, version: @doc.version + 1,
+                       content_updated_at: Time.current, updated_by: Current.user)
+        end
+      end
+      @doc.update!(title: params[:title]) if params[:title].present?
+      render json: { document: @doc.meta_json(role: @role) }
+    end
+
+    # DELETE /api/documents/:id -- the owner deletes it; anyone else leaves it
+    def destroy
+      if @role == :owner
+        @doc.destroy!
+      elsif Current.user
+        @doc.document_memberships.where(user: Current.user).delete_all
+      else
+        return forbidden
+      end
+      head :no_content
+    end
+
+    private
+
+    def load_document
+      @doc = Document.find(params[:id])
+      @role = @doc.role_for(user: Current.user, token: share_token)
+      raise ActiveRecord::RecordNotFound unless @role # 404, not 403: don't confirm it exists
+    end
+
+    def content_param
+      c = params.require(:content)
+      c.is_a?(String) ? c : c.to_unsafe_h.to_json
+    end
+
+    def touch_membership
+      return unless Current.user
+      @doc.document_memberships.where(user: Current.user).update_all(last_opened_at: Time.current)
+    end
+
+    def forbidden = render(json: { error: "forbidden" }, status: :forbidden)
+  end
+end

app/controllers/api/joins_controller.rb

@@ -0,0 +1,17 @@
+module Api
+  # POST /api/documents/:document_id/join { token }
+  # Redeems a share link. Signed in: the document is added to the account
+  # (a membership). Not signed in: only answers what the token grants -- the
+  # browser keeps the token and sends it along (X-Share-Token).
+  class JoinsController < BaseController
+    def create
+      doc = Document.find(params[:document_id])
+      link = doc.share_links.active.find_by(token: params.require(:token))
+      raise ActiveRecord::RecordNotFound unless link
+      if Current.user
+        DocumentMembership.grant!(document: doc, user: Current.user, role: link.role, source: :link, share_link: link)
+      end
+      render json: { document: doc.meta_json(role: doc.role_for(user: Current.user, token: link.token)) }
+    end
+  end
+end

app/controllers/api/me_controller.rb

@@ -0,0 +1,16 @@
+module Api
+  class MeController < BaseController
+    before_action :require_authentication, only: :update
+
+    # GET /api/me
+    def show
+      render json: { user: Current.user&.as_json }
+    end
+
+    # PATCH /api/me { display_name }
+    def update
+      Current.user.update!(params.permit(:display_name))
+      render json: { user: Current.user.as_json }
+    end
+  end
+end

app/controllers/api/shares_controller.rb

@@ -0,0 +1,74 @@
+module Api
+  # Everything about who has access to a document. Owner only.
+  class SharesController < BaseController
+    before_action :require_authentication
+    before_action :load_owned_document
+
+    # GET /api/documents/:document_id/share
+    def show
+      render json: share_json
+    end
+
+    # POST /api/documents/:document_id/share/links { role }
+    # One active link per role: creating one replaces (revokes) the previous.
+    def create_link
+      role = params.require(:role)
+      return render(json: { error: "invalid_role" }, status: :unprocessable_entity) unless ShareLink.roles.key?(role)
+      @doc.transaction do
+        @doc.share_links.active.where(role:).find_each(&:revoke!)
+        @doc.share_links.create!(role:, created_by: Current.user)
+      end
+      render json: share_json
+    end
+
+    # DELETE /api/documents/:document_id/share/links/:id
+    def revoke_link
+      @doc.share_links.active.find(params[:id]).revoke!
+      render json: share_json
+    end
+
+    # POST /api/documents/:document_id/share/invitations { email, role }
+    def invite
+      role = params.require(:role)
+      return render(json: { error: "invalid_role" }, status: :unprocessable_entity) unless MagicLink.roles.key?(role)
+      link = MagicLink.issue!(email: params.require(:email), purpose: :invitation, document: @doc, role:, invited_by: Current.user)
+      if link.email == Current.user.email
+        link.destroy!
+        return render(json: { error: "self_invite" }, status: :unprocessable_entity)
+      end
+      AuthMailer.invitation(link, link.token).deliver_later
+      render json: share_json
+    end
+
+    # PATCH /api/documents/:document_id/share/members/:user_id { role }
+    def update_member
+      m = @doc.document_memberships.find_by!(user_id: params[:user_id])
+      m.update!(role: params.require(:role))
+      render json: share_json
+    end
+
+    # DELETE /api/documents/:document_id/share/members/:user_id
+    def remove_member
+      @doc.document_memberships.where(user_id: params[:user_id]).delete_all
+      render json: share_json
+    end
+
+    private
+
+    def load_owned_document
+      @doc = Current.user.owned_documents.find(params[:document_id])
+    end
+
+    def share_json
+      {
+        links: @doc.share_links.active.order(:created_at).map(&:as_json),
+        members: @doc.document_memberships.includes(:user).order(:created_at).map do |m|
+          { user_id: m.user_id, name: m.user.name, email: m.user.email, role: m.role, source: m.source }
+        end,
+        invitations: MagicLink.usable.invitation.where(document: @doc).order(:created_at).map do |i|
+          { email: i.email, role: i.role, expires_at: i.expires_at.iso8601 }
+        end
+      }
+    end
+  end
+end