small-software 0.6.0__tar.gz → 0.8.0__tar.gz

{small_software-0.6.0 → small_software-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: small-software
-Version: 0.6.0
+Version: 0.8.0
 Summary: A cloud for small software: deploy team apps to Railway in one command, private by default, shared by work email
 Author: RuslanKazyradzi13
 License-Expression: MIT
@@ -30,20 +30,23 @@ Dynamic: license-file
 
 [Русская версия](https://github.com/RuslanKazyradzi13/small-software/blob/main/small-cli/README.ru.md)
 
-`small` deploys small team apps to Railway in one command and protects them with sign-in by work email or
-personal invite links.
+`small` deploys small team apps to Railway in one command and protects them with sign-in by work account (Google,
+Microsoft), work email or personal invite links.
 
 ```
 small init my-service    # skeleton: invite-link protected server, small.json, .gitignore
 cd my-service
 small deploy             # → https://my-service-3f9a.up.railway.app
 small open               # open with the invite link
-small access add ivan@company.com   # sign-in by work email, like sharing a Google Doc
-small mail resend        # how sign-in emails are sent
+small access add ivan@company.com   # who may sign in, like sharing a Google Doc
+small sso google         # "Sign in with Google" (or small sso microsoft)
+small mail resend        # or sign-in links by email
+small access log         # who signed in, when and how
 small access add bob     # or a personal link for bob (small access revoke bob to revoke it)
 small notify telegram    # access requests to Telegram
 small env set DEBUG=1    # environment variable in Railway and small.json
 small db add postgres    # database, DATABASE_URL in the app
+small volume add         # persistent disk: files and sign-in state survive deploys
 small domain add app.example.com   # custom domain
 small sleep on           # sleep when idle (saves money)
 small logs -f            # app logs
@@ -70,8 +73,25 @@ From source, in a clone of the repository:
 pip install ./small-cli
 ```
 
-**Windows.** `pip install` creates `small.exe`, which Smart App Control / Application Control may block because it
-is unsigned. If that happens, either:
+**Windows (recommended): one command in PowerShell.**
+
+```powershell
+irm https://raw.githubusercontent.com/RuslanKazyradzi13/small-software/main/install.ps1 | iex
+```
+
+It installs small into its own Python environment in `%LOCALAPPDATA%\Programs\small` and adds a `small`
+command that Smart App Control does not block (there is no unsigned `small.exe`). Needs Python 3.9+, no admin
+rights; run it again to upgrade. Uninstall:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/RuslanKazyradzi13/small-software/main/install.ps1))) -Uninstall
+```
+
+Values with `&` or `|` (URLs, for example) need PowerShell's stop-parsing token:
+`small --% env set "URL=https://x?a=1&b=2"`.
+
+**Windows with pip.** `pip install` creates `small.exe`, which Smart App Control / Application Control may
+block because it is unsigned. If that happens, either:
 
 - run small through Python, which works everywhere: `python -m small_cli deploy` (any command works this way);
 - or add the `small-cli` folder of a clone to `PATH`, and `small.cmd` will serve the `small` command. Run this in
@@ -154,12 +174,15 @@ The sample apps are in English: both the page text and the code comments.
   `small deploy` passes `ACCESS_TOKEN` from `small.json` to Railway. The app opens at
   `https://<domain>/?token=<ACCESS_TOKEN>`; without the token visitors get a 403 page with a **Request access**
   button. The server listens on `$HOST:$PORT`, by default `0.0.0.0` and the `PORT` set by Railway.
-- **The `streamlit` template.** Streamlit is not a WSGI app, so `magic_link.py` cannot wrap it. The same logic is
-  built into `app.py` as `require_access()`: the same `ACCESS_TOKEN` and `ACCESS_REQUEST_URL`, an "Invite only"
-  screen and a **Request access** form that writes an `[access-request]` line to the log. Like magic-link, the
-  access screen follows the visitor's browser language (`ACCESS_LANG` forces one). There are two differences.
-  Streamlit cannot set cookies, so the token stays in the address bar, which is how access survives a page reload.
-  And Streamlit is a single-page app, so the "no access" screen is served with HTTP 200, not 403.
+- **The `streamlit` template.** Streamlit can't be wrapped in middleware, so `require_access()` in `app.py` uses
+  `MagicLinkGate` from `magic_link.py`: the same variables (`ACCESS_EMAILS`, `ACCESS_TOKEN`, `SESSION_SECRET`,
+  `ACCESS_REQUEST_URL`...), one-time links, limits and logs as the other templates, and the access screen follows the
+  visitor's browser language. Differences:
+  - Sign-in by email: the link leads to `https://<domain>/?t=...` and shows a **Sign in** button; only the click
+    signs in. The 30-day session is a signed cookie written by a tiny same-origin frame, so unlike in the other
+    templates it is **not HttpOnly**: don't render untrusted HTML in a protected app. **Sign out** is in the sidebar.
+  - Personal links keep the token in the address bar (`?token=`), which is how they survive a page reload.
+  - Streamlit is a single-page app, so the "no access" screen is served with HTTP 200, not 403.
   Railway runs `python app.py`, and `app.py` restarts itself through `streamlit run` on `$HOST:$PORT`.
   Run it locally the same way: `python app.py`.
 - **Name.** By default, the folder name plus a random suffix, for example `my-service-3f9a`. An explicit name in
@@ -204,6 +227,12 @@ Buttons on the card of a deployed app:
   The token only goes to the browser's address bar on navigation; it is not in the dashboard page data.
 - **Logs** opens a window with the last 200 lines of the app or build log (tabs **App** / **Build**).
   Requires `RAILWAY_API_TOKEN`; without it the button is disabled.
+- **Share** opens who has access: work emails, whole domains and personal-link names (never the links
+  themselves). Type `ivan@company.com`, `@company.com` or a name and click **Add**, or click **Revoke** next to
+  anyone. It does exactly what `small access add` / `revoke` does: updates small.json and Railway and restarts
+  the app. A new personal link is shown only once, with a Copy button, and works like a password. Requires
+  `RAILWAY_API_TOKEN`. The page and its requests are protected: a per-run key, `Host`/`Origin` checks, no
+  framing, JSON only.
 
 - **Port** 3000 by default; if it is busy, any free port is used. The URL is printed to stdout.
 - **The server listens on `127.0.0.1` only** and answers 403 to requests with a foreign `Host` (DNS rebinding
@@ -247,6 +276,46 @@ $10 per GB of memory, $0.15 per GB of volume. The result reads "≈ $X/mo at cur
 - **This is an estimate, not a bill.** Egress ($0.05/GB), the plan's free allowance ($5 on Hobby, $20 on Pro) and
   the subscription are not included. The exact amount is in Railway → Usage.
 
+## `small mcp`: AI agents (Claude Code, Cursor...)
+
+```
+small mcp
+```
+
+Runs an [MCP](https://modelcontextprotocol.io) server on stdin/stdout, so an AI coding agent can create, deploy and
+share apps itself: *"Deploy this folder and give ivan@company.com access."*
+
+**Connect it:**
+- **Claude Code:** `claude mcp add small -- small mcp` (Windows: `claude mcp add small -- cmd /c small mcp`).
+- **Cursor** (`~/.cursor/mcp.json`), **Claude Desktop**, **Windsurf** and other clients:
+
+  ```json
+  {"mcpServers": {"small": {"command": "small", "args": ["mcp"]}}}
+  ```
+
+  On Windows use `"command": "cmd", "args": ["/c", "small", "mcp"]`, or `"command": "python", "args": ["-m",
+  "small_cli", "mcp"]` if small was installed with pip.
+- `RAILWAY_API_TOKEN` must be in the environment the agent starts from. After setting it, restart the agent.
+
+**Tools:**
+
+| Tool | What it does |
+|---|---|
+| `init_app` | `small init`: a ready app from a template |
+| `deploy_app` | `small deploy`: returns the URL; progress is streamed while it builds |
+| `share_app` | `small access add`: an email, `@domain` or a personal-link name |
+| `revoke_access` | `small access revoke` |
+| `list_access` | `small access list` |
+| `list_apps` | apps under a folder with URL and latest deploy status |
+| `app_logs` | `small logs`: app or build log |
+| `set_env` | `small env set` / `unset` |
+
+- **No delete tool:** `small destroy` stays a terminal command.
+- **Prefer emails.** A personal link (a name instead of an email) is returned to the agent, so it passes through the
+  chat like any other text; with email sign-in nothing secret does.
+- The tools run the same code as the commands and answer in small's language (`SMALL_LANG`). Your MCP client
+  normally asks you before each tool call.
+
 ## `small deploy`
 
 ```
@@ -275,18 +344,22 @@ These commands work in the folder of a deployed app, that is, where `.small.json
 small link [folder] [--as NAME]                       # print the invite link
 small open [folder] [--as NAME]                       # the same + open it in the browser
 small access [list | add EMAIL|@DOMAIN|NAME | revoke EMAIL|NAME]   # who can sign in
+small access log [-n N] [--json]                   # who signed in, when and how
+small access signout EMAIL|@DOMAIN|--all           # end their sessions on all devices
+small sso [google [--client-id ID] | microsoft [--client-id ID] [--tenant T] | off [PROVIDER]]
 small mail [resend | smtp [--from FROM] [--to TO] | log | off]  # emails for sign-in by email
 small notify [telegram [--chat-id ID] | off]        # access requests to Telegram
 small env [list [--values] | set K=V ... | unset K ...] [--no-deploy]
 small db [list | add postgres | remove postgres [--yes]]
+small volume [add [--mount /data]]                  # persistent disk; no argument shows the status
 small domain [list | add DOMAIN [--port N] | remove DOMAIN]
 small sleep [on | off]                              # sleep mode; no argument shows the status
 small logs [folder] [--build] [-n N] [-f]            # log of the latest deploy
 small destroy [folder] [--yes]                       # remove from Railway
 ```
 
-Commands that change the app's variables (`access add` / `revoke`, `mail`, `notify`, `env set` / `unset`,
-`db add` / `remove`) and `sleep on` / `off` restart the app once. Add `--no-deploy` to skip the restart; the change
+Commands that change the app's variables (`access add` / `revoke` / `signout`, `sso`, `mail`, `notify`,
+`env set` / `unset`, `db add` / `remove`), `volume add` and `sleep on` / `off` restart the app once. Add `--no-deploy` to skip the restart; the change
 then takes effect on the next deploy.
 
 **`small link` / `small open`** build `https://<domain>/?token=<token>`.
@@ -299,15 +372,22 @@ then takes effect on the next deploy.
 
 **`small access`** controls who can open the app. There are two ways, and you can combine them.
 
-*By work email*, like sharing a Google Doc. This is the recommended way:
-- **`add ivan@company.com`** adds the address to `ACCESS_EMAILS`. Ivan opens the app, enters his email and gets a
-  message with a sign-in link: it works for 15 minutes and only once, and the browser remembers the sign-in for
-  30 days. Only someone who reads that mailbox can sign in, so passing the link on to someone else gives them
-  nothing.
+*By address*, like sharing a Google Doc. This is the recommended way:
+- **`add ivan@company.com`** adds the address to `ACCESS_EMAILS`. Ivan opens the app and proves the address is his:
+  with **Sign in with Google / Microsoft** (`small sso`), or by entering it and getting a sign-in link by email
+  (`small mail`) that works for 15 minutes and only once. The browser remembers the sign-in for 30 days. Passing a
+  link on gives nobody anything: only the owner of the mailbox or account gets in.
 - **`add @company.com`** lets in everyone with an address in that domain.
-- **`revoke ivan@company.com`** closes sign-in right after the restart, even in a browser that is already open.
-- The first `add` creates `SESSION_SECRET`, the key that signs links and sessions. Email sending must be set up:
-  `small mail`.
+- **`revoke ivan@company.com`** closes sign-in right after the restart, even in a browser that is already open. The
+  time also goes to `SESSIONS_REVOKED`, so if you add the address back later, the old sessions stay invalid.
+- **`signout ivan@company.com`** (or `@company.com`, or `--all`) ends the sessions on every device without taking
+  access away: for a lost laptop. People can do it themselves with **Sign out on all devices** if the app has a
+  volume (`small volume add`).
+- **`log`** prints who signed in, when, how (Google, Microsoft, email link, invite link) and from which IP, plus
+  refused sign-ins and access requests, across deploys: `magic_link` writes them as JSON log lines, and Railway
+  keeps them as long as your plan keeps logs. `--json` gives one object per line.
+- The first `add` creates `SESSION_SECRET`, the key that signs links and sessions. One way to sign in must be set up:
+  `small sso` or `small mail`.
 - `small` passes the address for links in emails to the app itself, in `PUBLIC_URL` (in Railway only): after the
   domain is renamed to `<name>.up.railway.app`, Railway keeps the old address in `RAILWAY_PUBLIC_DOMAIN`, and the
   links would lead to a 404. If you want links on your own domain, set `PUBLIC_URL` in `small.json`; `small` does
@@ -315,8 +395,7 @@ then takes effect on the next deploy.
 - Someone who is not on the list and enters their email gets the same "Check your email" response, and the owner
   receives an access request (in the log, and in Telegram if connected) with a ready-made
   `small access add their@address` command.
-- Works in the `python-http`, `fastapi` and `node-http` templates. `streamlit` supports personal links only for
-  now.
+- Works in all templates: `python-http`, `fastapi`, `node-http` and `streamlit` (see the `streamlit` notes above).
 
 *By personal invite link*:
 - **`add bob`** creates a token, adds it to `ACCESS_TOKEN` as `bob:token`, restarts the app and prints the link.
@@ -325,10 +404,26 @@ then takes effect on the next deploy.
   their access.
 
 - **`list`** shows who has access: addresses and names (tokens are hidden).
-- **Sign-in log.** Sign-ins show up in the log: `small logs | Select-String "signed in by"` (PowerShell; on
-  macOS/Linux use `grep`) → `signed in by email (ivan@company.com)` or `signed in by link (bob)`. With
-  `OWNER_LANG=ru` these lines are in Russian; search them with `Select-String`, not `findstr`, which reads the
-  argument and the text in different encodings and does not find Cyrillic.
+- **Sign-in log.** `small access log` (above). In the raw log (`small logs`) each sign-in is one JSON line, for
+  example `{"message": "[magic-link] signed in with Google: ivan@company.com, ip 203.0.113.7", "magic_link":
+  "sign_in", "method": "google", ...}`; Railway's log explorer filters them with `@magic_link:sign_in`.
+
+**`small sso`** sets up sign-in with a work account. Who may sign in is still the access list.
+- **`google`**: "Sign in with Google" for Google Workspace accounts and Gmail addresses. `small` prints what to do
+  in Google Cloud (about 5 minutes: an OAuth client of type Web application) and the exact redirect URI to register,
+  then asks for the client ID and secret (the secret from `GOOGLE_CLIENT_SECRET` or with hidden input).
+- **`microsoft`**: "Sign in with Microsoft" for the members of one Microsoft Entra organization. `small` prints the
+  steps (an app registration, single tenant, a client secret) and the redirect URI; `--tenant` takes the Directory
+  (tenant) ID or your domain (`company.com`), which `small` resolves to the ID.
+- **Checked before saving.** `small` shows the provider the client ID and secret; a wrong pair is refused and
+  nothing is saved.
+- **Which accounts count.** Google: verified Gmail addresses, or accounts of a Google Workspace organization; a
+  personal Google account registered with a company address is refused. Microsoft: members of your tenant only, not
+  guests and not other organizations. Details: [SECURITY.md](https://github.com/RuslanKazyradzi13/small-software/blob/main/SECURITY.md#threat-model).
+- **Redirect URI**: `https://<app>/_access/sso/callback`, or `https://<app>/` for `streamlit`. With your own domain,
+  set `PUBLIC_URL` in `small.json` first, and register that address.
+- If email sign-in isn't set up, the sign-in page shows only the provider buttons; with both, it shows both.
+- **`off [google|microsoft]`** turns one or both off; with no subcommand you get the status and the redirect URI.
 
 **`small mail`** sets how the app sends sign-in emails.
 - **`resend`** sends through [Resend](https://resend.com) over HTTPS. `small` takes the key from `RESEND_API_KEY`
@@ -379,6 +474,16 @@ then takes effect on the next deploy.
   status.
 - **`remove`** removes the domain.
 
+**`small volume`** gives the app a persistent disk (a Railway volume).
+- **`add`** creates one at `/data` (`--mount` for another path, outside `/app`) and restarts the app. The app can
+  keep files there; the path is in `RAILWAY_VOLUME_MOUNT_PATH`. With no subcommand you get the path and how much is
+  used.
+- **Sign-in state.** `magic_link` keeps it in `.magic-link.db` (SQLite) on the volume: used sign-in links stay used
+  after a restart, rate limits are shared by worker processes, and **Sign out on all devices** appears. Without a
+  volume this state lives in memory and a restart forgets it.
+- **Trade-off.** With a volume each deploy has a few seconds of downtime: two copies of the app can't share the disk.
+  A service has one volume.
+
 **`small sleep`** controls Railway's sleep mode (serverless).
 - **`on`**: with no incoming requests the app goes to sleep and uses no CPU or memory; the first request wakes it
   up in a few seconds. Handy for apps that are opened a couple of times a day.
@@ -501,8 +606,9 @@ The tests start a local mock of the Railway API (GraphQL + the upload endpoint)
 deploy, repeat deploy, failed build, crash, taken domain, several workspaces, wrong token, ignore rules.
 
 Template tests on real frameworks are skipped if the framework is not installed; the rest pass.
-- 6 `streamlit` tests: the access gate through `streamlit.testing.v1.AppTest` (with personal tokens) and the server
-  through `python app.py`.
+- `streamlit` tests: the access gate through `streamlit.testing.v1.AppTest` (personal tokens, sign-in by email:
+  form, one-time link, session cookie, revocation, sign out; sign-in with Google against a local provider, refusals,
+  sign out on all devices) and the server through `python app.py`.
 - 2 `fastapi` tests: `TestClient` and `uvicorn main:app` the way Railway runs it, plus a check that the token is
   hidden in the access log.
 
@@ -517,6 +623,11 @@ Dashboard buttons: the "Open via invite link" redirect and its protection agains
 token, with Railway and with Railway unavailable. Sleep mode and the cost estimate in the dashboard, Railway errors
 while computing the cost.
 
+`small sso`, `volume`, `access log` and `access signout` are tested against mocks of Railway, Google and Microsoft:
+the credential check, a wrong secret that saves nothing, resolving a domain to a tenant, the Streamlit and custom
+domain redirect URIs, old `magic_link` code, the volume and its mount path, the access log table, `--json` and the MCP
+tool, sign-outs by address, domain and `--all`, forgetting old sign-outs.
+
 `small sleep`, `db`, `domain` and `notify` are tested against mocks of Railway and the Telegram Bot API:
 - turning sleep on and off, turning it on again without requests, `--no-deploy`;
 - deploying the Postgres template with default values, the `DATABASE_URL` reference, a workflow error, removing

{small_software-0.6.0 → small_software-0.8.0}/README.md

@@ -2,20 +2,23 @@
 
 [Русская версия](https://github.com/RuslanKazyradzi13/small-software/blob/main/small-cli/README.ru.md)
 
-`small` deploys small team apps to Railway in one command and protects them with sign-in by work email or
-personal invite links.
+`small` deploys small team apps to Railway in one command and protects them with sign-in by work account (Google,
+Microsoft), work email or personal invite links.
 
 ```
 small init my-service    # skeleton: invite-link protected server, small.json, .gitignore
 cd my-service
 small deploy             # → https://my-service-3f9a.up.railway.app
 small open               # open with the invite link
-small access add ivan@company.com   # sign-in by work email, like sharing a Google Doc
-small mail resend        # how sign-in emails are sent
+small access add ivan@company.com   # who may sign in, like sharing a Google Doc
+small sso google         # "Sign in with Google" (or small sso microsoft)
+small mail resend        # or sign-in links by email
+small access log         # who signed in, when and how
 small access add bob     # or a personal link for bob (small access revoke bob to revoke it)
 small notify telegram    # access requests to Telegram
 small env set DEBUG=1    # environment variable in Railway and small.json
 small db add postgres    # database, DATABASE_URL in the app
+small volume add         # persistent disk: files and sign-in state survive deploys
 small domain add app.example.com   # custom domain
 small sleep on           # sleep when idle (saves money)
 small logs -f            # app logs
@@ -42,8 +45,25 @@ From source, in a clone of the repository:
 pip install ./small-cli
 ```
 
-**Windows.** `pip install` creates `small.exe`, which Smart App Control / Application Control may block because it
-is unsigned. If that happens, either:
+**Windows (recommended): one command in PowerShell.**
+
+```powershell
+irm https://raw.githubusercontent.com/RuslanKazyradzi13/small-software/main/install.ps1 | iex
+```
+
+It installs small into its own Python environment in `%LOCALAPPDATA%\Programs\small` and adds a `small`
+command that Smart App Control does not block (there is no unsigned `small.exe`). Needs Python 3.9+, no admin
+rights; run it again to upgrade. Uninstall:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/RuslanKazyradzi13/small-software/main/install.ps1))) -Uninstall
+```
+
+Values with `&` or `|` (URLs, for example) need PowerShell's stop-parsing token:
+`small --% env set "URL=https://x?a=1&b=2"`.
+
+**Windows with pip.** `pip install` creates `small.exe`, which Smart App Control / Application Control may
+block because it is unsigned. If that happens, either:
 
 - run small through Python, which works everywhere: `python -m small_cli deploy` (any command works this way);
 - or add the `small-cli` folder of a clone to `PATH`, and `small.cmd` will serve the `small` command. Run this in
@@ -126,12 +146,15 @@ The sample apps are in English: both the page text and the code comments.
   `small deploy` passes `ACCESS_TOKEN` from `small.json` to Railway. The app opens at
   `https://<domain>/?token=<ACCESS_TOKEN>`; without the token visitors get a 403 page with a **Request access**
   button. The server listens on `$HOST:$PORT`, by default `0.0.0.0` and the `PORT` set by Railway.
-- **The `streamlit` template.** Streamlit is not a WSGI app, so `magic_link.py` cannot wrap it. The same logic is
-  built into `app.py` as `require_access()`: the same `ACCESS_TOKEN` and `ACCESS_REQUEST_URL`, an "Invite only"
-  screen and a **Request access** form that writes an `[access-request]` line to the log. Like magic-link, the
-  access screen follows the visitor's browser language (`ACCESS_LANG` forces one). There are two differences.
-  Streamlit cannot set cookies, so the token stays in the address bar, which is how access survives a page reload.
-  And Streamlit is a single-page app, so the "no access" screen is served with HTTP 200, not 403.
+- **The `streamlit` template.** Streamlit can't be wrapped in middleware, so `require_access()` in `app.py` uses
+  `MagicLinkGate` from `magic_link.py`: the same variables (`ACCESS_EMAILS`, `ACCESS_TOKEN`, `SESSION_SECRET`,
+  `ACCESS_REQUEST_URL`...), one-time links, limits and logs as the other templates, and the access screen follows the
+  visitor's browser language. Differences:
+  - Sign-in by email: the link leads to `https://<domain>/?t=...` and shows a **Sign in** button; only the click
+    signs in. The 30-day session is a signed cookie written by a tiny same-origin frame, so unlike in the other
+    templates it is **not HttpOnly**: don't render untrusted HTML in a protected app. **Sign out** is in the sidebar.
+  - Personal links keep the token in the address bar (`?token=`), which is how they survive a page reload.
+  - Streamlit is a single-page app, so the "no access" screen is served with HTTP 200, not 403.
   Railway runs `python app.py`, and `app.py` restarts itself through `streamlit run` on `$HOST:$PORT`.
   Run it locally the same way: `python app.py`.
 - **Name.** By default, the folder name plus a random suffix, for example `my-service-3f9a`. An explicit name in
@@ -176,6 +199,12 @@ Buttons on the card of a deployed app:
   The token only goes to the browser's address bar on navigation; it is not in the dashboard page data.
 - **Logs** opens a window with the last 200 lines of the app or build log (tabs **App** / **Build**).
   Requires `RAILWAY_API_TOKEN`; without it the button is disabled.
+- **Share** opens who has access: work emails, whole domains and personal-link names (never the links
+  themselves). Type `ivan@company.com`, `@company.com` or a name and click **Add**, or click **Revoke** next to
+  anyone. It does exactly what `small access add` / `revoke` does: updates small.json and Railway and restarts
+  the app. A new personal link is shown only once, with a Copy button, and works like a password. Requires
+  `RAILWAY_API_TOKEN`. The page and its requests are protected: a per-run key, `Host`/`Origin` checks, no
+  framing, JSON only.
 
 - **Port** 3000 by default; if it is busy, any free port is used. The URL is printed to stdout.
 - **The server listens on `127.0.0.1` only** and answers 403 to requests with a foreign `Host` (DNS rebinding
@@ -219,6 +248,46 @@ $10 per GB of memory, $0.15 per GB of volume. The result reads "≈ $X/mo at cur
 - **This is an estimate, not a bill.** Egress ($0.05/GB), the plan's free allowance ($5 on Hobby, $20 on Pro) and
   the subscription are not included. The exact amount is in Railway → Usage.
 
+## `small mcp`: AI agents (Claude Code, Cursor...)
+
+```
+small mcp
+```
+
+Runs an [MCP](https://modelcontextprotocol.io) server on stdin/stdout, so an AI coding agent can create, deploy and
+share apps itself: *"Deploy this folder and give ivan@company.com access."*
+
+**Connect it:**
+- **Claude Code:** `claude mcp add small -- small mcp` (Windows: `claude mcp add small -- cmd /c small mcp`).
+- **Cursor** (`~/.cursor/mcp.json`), **Claude Desktop**, **Windsurf** and other clients:
+
+  ```json
+  {"mcpServers": {"small": {"command": "small", "args": ["mcp"]}}}
+  ```
+
+  On Windows use `"command": "cmd", "args": ["/c", "small", "mcp"]`, or `"command": "python", "args": ["-m",
+  "small_cli", "mcp"]` if small was installed with pip.
+- `RAILWAY_API_TOKEN` must be in the environment the agent starts from. After setting it, restart the agent.
+
+**Tools:**
+
+| Tool | What it does |
+|---|---|
+| `init_app` | `small init`: a ready app from a template |
+| `deploy_app` | `small deploy`: returns the URL; progress is streamed while it builds |
+| `share_app` | `small access add`: an email, `@domain` or a personal-link name |
+| `revoke_access` | `small access revoke` |
+| `list_access` | `small access list` |
+| `list_apps` | apps under a folder with URL and latest deploy status |
+| `app_logs` | `small logs`: app or build log |
+| `set_env` | `small env set` / `unset` |
+
+- **No delete tool:** `small destroy` stays a terminal command.
+- **Prefer emails.** A personal link (a name instead of an email) is returned to the agent, so it passes through the
+  chat like any other text; with email sign-in nothing secret does.
+- The tools run the same code as the commands and answer in small's language (`SMALL_LANG`). Your MCP client
+  normally asks you before each tool call.
+
 ## `small deploy`
 
 ```
@@ -247,18 +316,22 @@ These commands work in the folder of a deployed app, that is, where `.small.json
 small link [folder] [--as NAME]                       # print the invite link
 small open [folder] [--as NAME]                       # the same + open it in the browser
 small access [list | add EMAIL|@DOMAIN|NAME | revoke EMAIL|NAME]   # who can sign in
+small access log [-n N] [--json]                   # who signed in, when and how
+small access signout EMAIL|@DOMAIN|--all           # end their sessions on all devices
+small sso [google [--client-id ID] | microsoft [--client-id ID] [--tenant T] | off [PROVIDER]]
 small mail [resend | smtp [--from FROM] [--to TO] | log | off]  # emails for sign-in by email
 small notify [telegram [--chat-id ID] | off]        # access requests to Telegram
 small env [list [--values] | set K=V ... | unset K ...] [--no-deploy]
 small db [list | add postgres | remove postgres [--yes]]
+small volume [add [--mount /data]]                  # persistent disk; no argument shows the status
 small domain [list | add DOMAIN [--port N] | remove DOMAIN]
 small sleep [on | off]                              # sleep mode; no argument shows the status
 small logs [folder] [--build] [-n N] [-f]            # log of the latest deploy
 small destroy [folder] [--yes]                       # remove from Railway
 ```
 
-Commands that change the app's variables (`access add` / `revoke`, `mail`, `notify`, `env set` / `unset`,
-`db add` / `remove`) and `sleep on` / `off` restart the app once. Add `--no-deploy` to skip the restart; the change
+Commands that change the app's variables (`access add` / `revoke` / `signout`, `sso`, `mail`, `notify`,
+`env set` / `unset`, `db add` / `remove`), `volume add` and `sleep on` / `off` restart the app once. Add `--no-deploy` to skip the restart; the change
 then takes effect on the next deploy.
 
 **`small link` / `small open`** build `https://<domain>/?token=<token>`.
@@ -271,15 +344,22 @@ then takes effect on the next deploy.
 
 **`small access`** controls who can open the app. There are two ways, and you can combine them.
 
-*By work email*, like sharing a Google Doc. This is the recommended way:
-- **`add ivan@company.com`** adds the address to `ACCESS_EMAILS`. Ivan opens the app, enters his email and gets a
-  message with a sign-in link: it works for 15 minutes and only once, and the browser remembers the sign-in for
-  30 days. Only someone who reads that mailbox can sign in, so passing the link on to someone else gives them
-  nothing.
+*By address*, like sharing a Google Doc. This is the recommended way:
+- **`add ivan@company.com`** adds the address to `ACCESS_EMAILS`. Ivan opens the app and proves the address is his:
+  with **Sign in with Google / Microsoft** (`small sso`), or by entering it and getting a sign-in link by email
+  (`small mail`) that works for 15 minutes and only once. The browser remembers the sign-in for 30 days. Passing a
+  link on gives nobody anything: only the owner of the mailbox or account gets in.
 - **`add @company.com`** lets in everyone with an address in that domain.
-- **`revoke ivan@company.com`** closes sign-in right after the restart, even in a browser that is already open.
-- The first `add` creates `SESSION_SECRET`, the key that signs links and sessions. Email sending must be set up:
-  `small mail`.
+- **`revoke ivan@company.com`** closes sign-in right after the restart, even in a browser that is already open. The
+  time also goes to `SESSIONS_REVOKED`, so if you add the address back later, the old sessions stay invalid.
+- **`signout ivan@company.com`** (or `@company.com`, or `--all`) ends the sessions on every device without taking
+  access away: for a lost laptop. People can do it themselves with **Sign out on all devices** if the app has a
+  volume (`small volume add`).
+- **`log`** prints who signed in, when, how (Google, Microsoft, email link, invite link) and from which IP, plus
+  refused sign-ins and access requests, across deploys: `magic_link` writes them as JSON log lines, and Railway
+  keeps them as long as your plan keeps logs. `--json` gives one object per line.
+- The first `add` creates `SESSION_SECRET`, the key that signs links and sessions. One way to sign in must be set up:
+  `small sso` or `small mail`.
 - `small` passes the address for links in emails to the app itself, in `PUBLIC_URL` (in Railway only): after the
   domain is renamed to `<name>.up.railway.app`, Railway keeps the old address in `RAILWAY_PUBLIC_DOMAIN`, and the
   links would lead to a 404. If you want links on your own domain, set `PUBLIC_URL` in `small.json`; `small` does
@@ -287,8 +367,7 @@ then takes effect on the next deploy.
 - Someone who is not on the list and enters their email gets the same "Check your email" response, and the owner
   receives an access request (in the log, and in Telegram if connected) with a ready-made
   `small access add their@address` command.
-- Works in the `python-http`, `fastapi` and `node-http` templates. `streamlit` supports personal links only for
-  now.
+- Works in all templates: `python-http`, `fastapi`, `node-http` and `streamlit` (see the `streamlit` notes above).
 
 *By personal invite link*:
 - **`add bob`** creates a token, adds it to `ACCESS_TOKEN` as `bob:token`, restarts the app and prints the link.
@@ -297,10 +376,26 @@ then takes effect on the next deploy.
   their access.
 
 - **`list`** shows who has access: addresses and names (tokens are hidden).
-- **Sign-in log.** Sign-ins show up in the log: `small logs | Select-String "signed in by"` (PowerShell; on
-  macOS/Linux use `grep`) → `signed in by email (ivan@company.com)` or `signed in by link (bob)`. With
-  `OWNER_LANG=ru` these lines are in Russian; search them with `Select-String`, not `findstr`, which reads the
-  argument and the text in different encodings and does not find Cyrillic.
+- **Sign-in log.** `small access log` (above). In the raw log (`small logs`) each sign-in is one JSON line, for
+  example `{"message": "[magic-link] signed in with Google: ivan@company.com, ip 203.0.113.7", "magic_link":
+  "sign_in", "method": "google", ...}`; Railway's log explorer filters them with `@magic_link:sign_in`.
+
+**`small sso`** sets up sign-in with a work account. Who may sign in is still the access list.
+- **`google`**: "Sign in with Google" for Google Workspace accounts and Gmail addresses. `small` prints what to do
+  in Google Cloud (about 5 minutes: an OAuth client of type Web application) and the exact redirect URI to register,
+  then asks for the client ID and secret (the secret from `GOOGLE_CLIENT_SECRET` or with hidden input).
+- **`microsoft`**: "Sign in with Microsoft" for the members of one Microsoft Entra organization. `small` prints the
+  steps (an app registration, single tenant, a client secret) and the redirect URI; `--tenant` takes the Directory
+  (tenant) ID or your domain (`company.com`), which `small` resolves to the ID.
+- **Checked before saving.** `small` shows the provider the client ID and secret; a wrong pair is refused and
+  nothing is saved.
+- **Which accounts count.** Google: verified Gmail addresses, or accounts of a Google Workspace organization; a
+  personal Google account registered with a company address is refused. Microsoft: members of your tenant only, not
+  guests and not other organizations. Details: [SECURITY.md](https://github.com/RuslanKazyradzi13/small-software/blob/main/SECURITY.md#threat-model).
+- **Redirect URI**: `https://<app>/_access/sso/callback`, or `https://<app>/` for `streamlit`. With your own domain,
+  set `PUBLIC_URL` in `small.json` first, and register that address.
+- If email sign-in isn't set up, the sign-in page shows only the provider buttons; with both, it shows both.
+- **`off [google|microsoft]`** turns one or both off; with no subcommand you get the status and the redirect URI.
 
 **`small mail`** sets how the app sends sign-in emails.
 - **`resend`** sends through [Resend](https://resend.com) over HTTPS. `small` takes the key from `RESEND_API_KEY`
@@ -351,6 +446,16 @@ then takes effect on the next deploy.
   status.
 - **`remove`** removes the domain.
 
+**`small volume`** gives the app a persistent disk (a Railway volume).
+- **`add`** creates one at `/data` (`--mount` for another path, outside `/app`) and restarts the app. The app can
+  keep files there; the path is in `RAILWAY_VOLUME_MOUNT_PATH`. With no subcommand you get the path and how much is
+  used.
+- **Sign-in state.** `magic_link` keeps it in `.magic-link.db` (SQLite) on the volume: used sign-in links stay used
+  after a restart, rate limits are shared by worker processes, and **Sign out on all devices** appears. Without a
+  volume this state lives in memory and a restart forgets it.
+- **Trade-off.** With a volume each deploy has a few seconds of downtime: two copies of the app can't share the disk.
+  A service has one volume.
+
 **`small sleep`** controls Railway's sleep mode (serverless).
 - **`on`**: with no incoming requests the app goes to sleep and uses no CPU or memory; the first request wakes it
   up in a few seconds. Handy for apps that are opened a couple of times a day.
@@ -473,8 +578,9 @@ The tests start a local mock of the Railway API (GraphQL + the upload endpoint)
 deploy, repeat deploy, failed build, crash, taken domain, several workspaces, wrong token, ignore rules.
 
 Template tests on real frameworks are skipped if the framework is not installed; the rest pass.
-- 6 `streamlit` tests: the access gate through `streamlit.testing.v1.AppTest` (with personal tokens) and the server
-  through `python app.py`.
+- `streamlit` tests: the access gate through `streamlit.testing.v1.AppTest` (personal tokens, sign-in by email:
+  form, one-time link, session cookie, revocation, sign out; sign-in with Google against a local provider, refusals,
+  sign out on all devices) and the server through `python app.py`.
 - 2 `fastapi` tests: `TestClient` and `uvicorn main:app` the way Railway runs it, plus a check that the token is
   hidden in the access log.
 
@@ -489,6 +595,11 @@ Dashboard buttons: the "Open via invite link" redirect and its protection agains
 token, with Railway and with Railway unavailable. Sleep mode and the cost estimate in the dashboard, Railway errors
 while computing the cost.
 
+`small sso`, `volume`, `access log` and `access signout` are tested against mocks of Railway, Google and Microsoft:
+the credential check, a wrong secret that saves nothing, resolving a domain to a tenant, the Streamlit and custom
+domain redirect URIs, old `magic_link` code, the volume and its mount path, the access log table, `--json` and the MCP
+tool, sign-outs by address, domain and `--all`, forgetting old sign-outs.
+
 `small sleep`, `db`, `domain` and `notify` are tested against mocks of Railway and the Telegram Bot API:
 - turning sleep on and off, turning it on again without requests, `--no-deploy`;
 - deploying the Postgres template with default values, the `DATABASE_URL` reference, a workflow error, removing

{small_software-0.6.0 → small_software-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "small-software"
-version = "0.6.0"
+version = "0.8.0"
 description = "A cloud for small software: deploy team apps to Railway in one command, private by default, shared by work email"
 license = "MIT"
 license-files = ["LICENSE"]

small_software-0.8.0/small_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.8.0"