feature/gresiq-v1
claude/smbcloud-github-app-k9641p
development
feature/apps
feature/build-release
feature/ci-docs
feature/ci-ruby-gems
feature/cicd
feature/completion
feature/dist-nuget
feature/fix-ci-sdk-pypi-rubygem
feature/fix-clippy-on-stable-channel
feature/fix-deployment-script
feature/github-email
feature/gresiq-v1
feature/project-new-structure
feature/rsync-deploy
feature/ruby-runner
feature/sdk-npm
feature/sdk-workflows
feature/smbcloud-cli-release-npm
feature/smbcloud-deploy
feature/wasm
main
release/v0.7.4
| 1 | --- |
| 2 | name: smbcloud-auth |
| 3 | description: Use when building, debugging, or extending smbCloud authentication across the Rails auth service, the web console, the Rust networking SDK, and Tauri client apps. Covers platform clients vs tenant auth apps, AuthUser signup/sign-in/confirmation, shared auth apps across projects, and development vs production app credentials. |
| 4 | --- |
| 5 | |
| 6 | # smbCloud Auth |
| 7 | |
| 8 | Use this skill when work touches any part of the smbCloud auth stack: |
| 9 | |
| 10 | - `smbcloud-api` Rails auth service |
| 11 | - `smbcloud-web-console` Next.js admin UI |
| 12 | - `smbcloud-cli/crates/smbcloud-auth` Rust SDK |
| 13 | - Tauri apps such as Rumi Learn Persian and PBJ Komplit |
| 14 | |
| 15 | ## Core model |
| 16 | |
| 17 | There are two auth planes. Do not mix them. |
| 18 | |
| 19 | ### 1. Platform clients |
| 20 | |
| 21 | These are smbCloud's own apps: |
| 22 | |
| 23 | - `web` |
| 24 | - `cli` |
| 25 | - `sigit` |
| 26 | - `moovibe` |
| 27 | - `webconsole` |
| 28 | |
| 29 | They authenticate smbCloud operator users through platform endpoints such as: |
| 30 | |
| 31 | - `POST /v1/users/sign_in` |
| 32 | - `POST /v1/users` |
| 33 | |
| 34 | They must use the platform client validator, not tenant app validation. |
| 35 | |
| 36 | ### 2. Tenant auth apps |
| 37 | |
| 38 | These are customer-facing apps such as Rumi or PBJ Komplit. |
| 39 | |
| 40 | They authenticate end users through: |
| 41 | |
| 42 | - `POST /v1/client/users` |
| 43 | - `POST /v1/client/users/sign_in` |
| 44 | - `GET /v1/client/me` |
| 45 | - `DELETE /v1/client/me` |
| 46 | - `DELETE /v1/client/users/sign_out` |
| 47 | - `GET /v1/client/users/confirmation` |
| 48 | |
| 49 | The tenant auth domain is: |
| 50 | |
| 51 | - `AuthApp` |
| 52 | - `AuthAppSecret` |
| 53 | - `AuthUser` |
| 54 | |
| 55 | Tenant apps must use `AuthAppClientAuthenticatable` and must not go through platform `/v1/users`. |
| 56 | |
| 57 | ## Multi-project auth apps |
| 58 | |
| 59 | Current rule: |
| 60 | |
| 61 | - one `AuthApp` has an owner project via `auth_apps.project_id` |
| 62 | - one `AuthApp` can be shared with other projects through `auth_app_projects` |
| 63 | - one project can point to only one auth app |
| 64 | |
| 65 | If a workspace/project should reuse an existing auth app, attach it instead of creating a duplicate. |
| 66 | |
| 67 | ## Rails conventions |
| 68 | |
| 69 | When editing `smbcloud-api`: |
| 70 | |
| 71 | - Platform operator auth stays under `User` |
| 72 | - Tenant app auth stays under `AuthUser` |
| 73 | - Do not reuse `OauthApplication` for tenant end-user login |
| 74 | - Do not hardcode tenant app validation in platform controllers |
| 75 | |
| 76 | ### AuthUser signup/sign-in rules |
| 77 | |
| 78 | - Signup creates an `AuthUser` scoped to `current_auth_app` |
| 79 | - Signup sends confirmation email |
| 80 | - Do not auto-set `confirmed_at` |
| 81 | - Sign-in returns `EmailNotVerified` until email is confirmed |
| 82 | - Deletion removes the currently authenticated `AuthUser` |
| 83 | |
| 84 | ### Mail flow |
| 85 | |
| 86 | For tenant users, use the explicit confirmation flow already established: |
| 87 | |
| 88 | - custom mailer for `AuthUser` |
| 89 | - confirmation link to `/v1/client/users/confirmation?confirmation_token=...` |
| 90 | |
| 91 | Do not claim email confirmation exists unless the mailer and route are actually wired. |
| 92 | |
| 93 | ## Rust SDK conventions |
| 94 | |
| 95 | The Rust client surface lives in: |
| 96 | |
| 97 | - `smbcloud-cli/crates/smbcloud-auth` |
| 98 | |
| 99 | When changing tenant app auth: |
| 100 | |
| 101 | - keep tenant auth on `/v1/client/*` |
| 102 | - preserve `AccountStatus` mapping: |
| 103 | - `NotFound` |
| 104 | - `Ready { access_token }` |
| 105 | - `Incomplete { status }` |
| 106 | - `request_login` depends on `422` + `error_code` for incomplete accounts |
| 107 | |
| 108 | If the backend changes error shape or status codes, update the Rust parser accordingly. |
| 109 | |
| 110 | ## Tauri client conventions |
| 111 | |
| 112 | For Rumi/PBJ-style apps: |
| 113 | |
| 114 | - use a dedicated `src-tauri/src/smbcloud/mod.rs` |
| 115 | - expose commands for: |
| 116 | - `signup_user` |
| 117 | - `sign_in_user` |
| 118 | - `current_user` |
| 119 | - `sign_out_user` |
| 120 | - `delete_current_user` |
| 121 | - `is_debug_build` |
| 122 | - store auth state in plugin-store: |
| 123 | - access token |
| 124 | - provider |
| 125 | - auth environment |
| 126 | - language |
| 127 | |
| 128 | ### Environment handling |
| 129 | |
| 130 | Keep development and production app credentials separate. |
| 131 | |
| 132 | Preferred pattern: |
| 133 | |
| 134 | - development credentials for local auth service |
| 135 | - production credentials for hosted auth service |
| 136 | - switch via a Rust `AuthEnvironment` enum |
| 137 | - expose the switch in debug builds only |
| 138 | |
| 139 | Recommended env variable names: |
| 140 | |
| 141 | - `SMBCLOUD_APP_ID_DEV` |
| 142 | - `SMBCLOUD_APP_SECRET_DEV` |
| 143 | - `SMBCLOUD_APP_ID_PRODUCTION` |
| 144 | - `SMBCLOUD_APP_SECRET_PRODUCTION` |
| 145 | |
| 146 | ### macOS Tauri dev builds |
| 147 | |
| 148 | `tauri.conf.json` `minimumSystemVersion` is not enough for `tauri dev`. |
| 149 | |
| 150 | For apps that link Swift-based plugins such as `tauri-plugin-iap`, add `src-tauri/.cargo/config.toml` with: |
| 151 | |
| 152 | - `MACOSX_DEPLOYMENT_TARGET=14.0` |
| 153 | - `-mmacosx-version-min=14.0` for both Apple targets |
| 154 | - host `CC` and `CXX` overrides to `/usr/bin/clang` and `/usr/bin/clang++` |
| 155 | |
| 156 | If you see `libswift_Concurrency.dylib` at runtime, fix Cargo/macOS config first. |
| 157 | |
| 158 | ## Web console conventions |
| 159 | |
| 160 | The admin UI lives in `smbcloud-web-console`. |
| 161 | |
| 162 | Use the `Auth` area, not generic settings pages, for tenant auth app management. |
| 163 | |
| 164 | Expected behavior: |
| 165 | |
| 166 | - scope auth view to selected workspace/project |
| 167 | - if workspace has an auth app, show the app and its users |
| 168 | - if not, allow: |
| 169 | - creating a new auth app |
| 170 | - attaching an existing tenant auth app |
| 171 | - show app id in list views |
| 172 | - hide app secret by default on detail views |
| 173 | - show linked/shared workspaces on detail pages |
| 174 | |
| 175 | ## Typical change flow |
| 176 | |
| 177 | 1. Decide whether the change is platform auth or tenant auth. |
| 178 | 2. Update Rails first. |
| 179 | 3. Update Rust SDK endpoints/parsing if the API contract changed. |
| 180 | 4. Update Tauri clients to match. |
| 181 | 5. Update the web console if auth app management changed. |
| 182 | 6. Validate end-to-end. |
| 183 | |
| 184 | ## Validation |
| 185 | |
| 186 | Use the smallest relevant checks. |
| 187 | |
| 188 | ### Rails |
| 189 | |
| 190 | - `bundle exec rails routes | grep 'v1/client\|auth_apps'` |
| 191 | - `ruby -c` on touched controller/model/mailer files |
| 192 | - `bundle exec rails db:migrate` if schema changed |
| 193 | |
| 194 | ### Rust SDK |
| 195 | |
| 196 | - `cargo check -p smbcloud-auth` |
| 197 | |
| 198 | ### Tauri apps |
| 199 | |
| 200 | - `cargo check` in `src-tauri` |
| 201 | - `pnpm build` in the app root when frontend changed |
| 202 | |
| 203 | ### Web console |
| 204 | |
| 205 | - `pnpm build` |
| 206 | |
| 207 | ## Common mistakes |
| 208 | |
| 209 | - Sending tenant app credentials to `/v1/users` |
| 210 | - Using `OauthApplication` instead of `AuthApp` for tenant login |
| 211 | - Replacing platform client validation with tenant auth app validation |
| 212 | - Auto-confirming `AuthUser` while telling the client to check email |
| 213 | - Forgetting that `tauri dev` ignores `tauri.conf.json` macOS minimum version |