1 file changed
+213
.agents/skills/smbcloud-auth/SKILL.md
new
+213
@@ -0,0 +1,213 @@
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-networking-account` 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-networking-account`
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-networking-account`
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