libredb / libredb/libredb-studio

docs: nothing tells a team of three or more that per-person logins and workspaces already work

Open Beginner friendly
#853 0 comments 0 reactions 0 assignees View on GitHub
documentation good first issue help wanted
Dominant language
TypeScript
Stars
726
Forks
119
Avg merge
7h 47m
Merged PRs (30d)
265

Description

A team of three or more people can already give everyone their own login, their own saved connections and their own line in the audit log. Nothing in the docs says so, so people do not find it. It came up in #784, where the reporter had concluded the product supported two accounts and nothing more.

This is a documentation-only task. No code changes, no new facts to discover: everything you need to write is below, already measured. It is a good first contribution.

## The gap

`docs/STORAGE.md` has a "Which Mode Should I Use?" table at `:50-57` with a **Multi-User** column that says No for Local and Yes for SQLite and PostgreSQL. That is correct but it is the only hint anywhere, and it says nothing about how the people become distinct users in the first place.

`docs/OIDC.md` explains how to configure each identity provider, but never says why a small team would want one, or that pairing it with server storage is what gives each person a private workspace.

So the two halves of the answer live in two files and neither points at the other.

## What is true, and may be stated

These were measured on `main` at 2703ddc6 against Keycloak 26.4 with three users, with storage on SQLite. Write prose from them; do not add claims beyond them.

- With `NEXT_PUBLIC_AUTH_PROVIDER=oidc`, the number of people who can use Studio is whatever the identity provider allows. Studio holds no account list of its own in this mode.
- With `STORAGE_PROVIDER=sqlite` or `postgres`, each person's connections, saved queries and settings are stored under their own key. The partition key is the username from the session, and the browser never gets to choose it. One user's `GET /api/storage` returns only their own rows.
- The audit log names the individual. A login and a permission denial both record the acting user, so "who ran this" has an answer.
- Roles come from the identity provider through `OIDC_ROLE_CLAIM` and `OIDC_ADMIN_ROLES`. Studio has two roles, `admin` and `user`.
- Removing someone is a change in the identity provider. No shared password has to be rotated.
- Without OIDC, the local email/password provider is limited to one admin plus one optional user. That limit is tracked in #784.

## What to write

**1. `docs/STORAGE.md`, right after the mode table at `:57`.** A short paragraph, three or four sentences, saying that server storage is what gives each person their own workspace, that the identity comes from the login, and that for a team of three or more this is meant to be paired with SSO. Link to `docs/OIDC.md`.

**2. `docs/OIDC.md`, in the Quick Start section at `:52`.** A short paragraph saying who this is for: teams past the one-admin-plus-one-user shape, who want individual logins, per-person workspaces and an audit trail that names people. Say that it is meant to be paired with `STORAGE_PROVIDER=sqlite` or `postgres`, and link to `docs/STORAGE.md`.

Keep both under roughly 80 words. These are signposts, not a new guide. Match the surrounding style of each file.

## Rules

- English, and no emoji. Match the heading style and tone already in each file.
- One sentence per physical line in Markdown, so a later one-sentence edit shows up as a one-line diff. This is a repo convention; look at a recently edited section for the shape.
- Do not restate the setup steps. Link to them.
- Do not claim anything not in the list above. In particular do not say the local email/password provider supports more than two accounts, and do not promise per-user isolation in the default `local` storage mode: in that mode everything lives in the browser, so two people on the same browser profile share one workspace.
- If you update either file's Table of Contents, update both the entry and the anchor, and check the anchor actually resolves.

## Done when

- Someone reading `docs/STORAGE.md` from the top learns that a team gets per-person workspaces and how.
- Someone reading `docs/OIDC.md` from the top learns why a small team would turn SSO on, not only how.
- The two files point at each other.
- `bun run readme:check` passes, and `bun run test` is green. No source files changed, so coverage is unaffected.

## How to verify your own change

Read each file from the top as though you had never seen the product, and stop at the point where you would have given up looking. If your new paragraph is not above that point, move it up.

Contributor guide

Open the contributing guide

Research direction

Read the mode table in docs/STORAGE.md around lines 50-57 and the Quick Start section in docs/OIDC.md around line 52, then inspect a recently edited Markdown section for the one-sentence-per-line convention. Add the two short cross-linked signposts using only the stated facts, and verify with bun run readme:check and bun run test.

Written by the indexing model from the issue text.

Assessment

Tech stack
bun, postgres, sqlite
Domain
authentication, databases, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
92/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.