diff --git a/README.md b/README.md index ea628a1..47865b9 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The server behind live, shared models in [Archify Diagram Viewer](https://marketplace.visualstudio.com/items?itemName=root-at-skic.archify-vscode-ext). People edit one model at the same time and see each other type. Every edit is kept, versions are taken on their own, and anyone can publish one by hand. -One Rust process and PostgreSQL. The design, with its decisions, is the Archify model in `ws-storm/2026-10-30-archify-sync-backend/`. +One Rust process and PostgreSQL. ## How it works @@ -14,7 +14,7 @@ One Rust process and PostgreSQL. The design, with its decisions, is the Archify - **Publish (1.0, 2.0, …):** marked by hand, with a name. - **Restore:** brings an earlier version back as a new edit and a new version; history is never rewritten. - **Update log:** taking a version compacts it. -- **Sign-in.** The editor opens `/authorize` in the browser and gets a one-time code back through its URI handler. It exchanges the code with its PKCE verifier for an access token (JWT, 15 minutes) and a refresh token. The refresh token is single use: reusing one signs out the whole session. +- **Sign-in.** The editor opens `/authorize` in the browser and gets a one-time code back: on the desktop through a one-off listener on `127.0.0.1`, in remote and web editors through its URI handler (`vscode://…/auth`). After sign-in the server shows a page that opens the editor, with a button for when the browser holds the link back. The editor exchanges the code with its PKCE verifier for an access token (JWT, 15 minutes) and a refresh token. The refresh token is single use: reusing one signs out the whole session. - **First start.** With single sign-on there is no setup step: the identity provider says who may sign in and who is admin, and the first sign-in makes the organisation (named after `ARCHIFY_SYNC_NAME`). Without single sign-on, a server without accounts prints a first-start code in its log; the first person to use it at `/setup` becomes the admin. - **Invites.** An invite link (`/join/`) opens the extension. Someone new makes an account on the sign-in page, so no mail server is needed. With single sign-on, the identity provider is the only way in: sign-in goes straight to it, with no password form, and an invited person signs in there. @@ -47,7 +47,7 @@ docker compose logs server | grep "with code" ## Kubernetes -The homelab deployment is in [archify-vscode-ext-sync-gitops](https://gitea.lego-cloud.eu/vscode-extensions/archify-vscode-ext-sync-gitops) (rendered from `archify-vscode-ext-sync-gitops-tmpl`); Argo CD takes this chart from here. +For Argo CD, [archify-vscode-ext-sync-gitops-tmpl](https://gitea.lego-cloud.eu/vscode-extensions/archify-vscode-ext-sync-gitops-tmpl) is a Copier template that renders an app-of-apps with this chart, its values and, optionally, its secrets through External Secrets. The chart is in `charts/archify-sync`. It always runs one pod with the `Recreate` strategy: one server holds the live copy of each space, and the extension works offline while the pod is replaced. Probes use `/healthz` and `/readyz`; on `SIGTERM` the server stores a snapshot of every open space. @@ -69,7 +69,7 @@ The server is then at `http://localhost:18081`. ## Single sign-on (OIDC) -With an OpenID Connect provider (Keycloak, Authentik, Entra ID, …) the sign-in page shows **Sign in with Keycloak** above the password form. Nothing changes in the extension: it opens the same page, and the provider sends the person back to `/oidc/callback`. People are matched by the provider's issuer and subject, never by name; a new person gets an account named after `preferred_username` (`ana`, or `ana-2` when `ana` is taken). +With an OpenID Connect provider (Keycloak, Authentik, Entra ID, …) the provider is the only way in: `/authorize` goes straight to it, there is no password form, and no local accounts are made. Nothing changes in the extension: it opens the same page, and the provider sends the person back to `/oidc/callback`. People are matched by the provider's issuer and subject, never by name; a new person gets an account named after `preferred_username` (`ana`, or `ana-2` when `ana` is taken). Who gets in: @@ -77,7 +77,7 @@ Who gets in: - **No allowed groups**: anyone the provider signs in, but a new person needs an invite link the first time. - **Admin groups** (`ARCHIFY_SYNC_OIDC_ADMIN_GROUPS=archify-admins`): their members are admins of the server. -The first admin is still set up with a password on `/setup`; keep that account as the way in when the provider is down. +There is no `/setup` step: the first sign-in by an allowed or admin member makes the organisation, named after `ARCHIFY_SYNC_NAME`. ### The client at the provider