phonograph/README.md

# Phonograph

A friendly, collaborative PostgreSQL derivative for nerds of all stripes.

![Screenshot of multi-cursor editing, as well as a dropdown menu with a highlighted option labeled "PostgreSQL credentials"](./docs/screenshot_multi_cursor.png)

# Development Quickstart

The Phonograph repository comes with a [mise-en-place](https://mise.jdx.dev/)
configuration to automatically manage the development environment:

- `mise install` installs language runtimes and tooling.
- `mise run build-css && mise run build-svelte` builds browser assets.
- `mise run docker-services` runs a Postgres container for local development.
- `mise run server` compiles and runs the server with the dev profile.

## Configuration

Refer to [the .env.example file](./.env.example) for configuration options.

# LLM Code Policy

Large language model code generation is permitted sparingly in very limited
cases, for example for completing clearly defined transformations which span
multiple files and are not supported by conventional code actions. All code
generated by LLMs must be thoroughly and frequently reviewed by the author,
before committing affected work.

As of this writing, models display a strong bias towards patterns which are well
represented in public open source projects. This can cause them to tend towards
suboptimal one-size-fits-most or simply outdated coding practices in certain
circumstances. LLM assistance should be sufficiently constrained to avoid
allowing outputs to dictate or implicitly guide significant design decisions.

Furthermore, current language models broadly behave adversarily, in the sense
that they are optimized to make perceiving model outputs versus non-model
outputs as difficult as possible. This can make generated code uniquely
challenging to review effectively. In this context, non-trivial business logic,
particularly logic with security implications, may not be implemented with
direct assistance from LLM tools.

Examples of LLM-assisted changes in practice:

- Replacing SVG icons with similar webfont icons from a different icon pack.
  (Revision `ztrnxzqv` (Git `a8dd49f7`))

# The Phonograph Authorization Model

Postgres provides a sophisticated role based access control (RBAC) system, which
Phonograph leverages to apply permissions consistently across the web UI and
inbound PostgreSQL[^1] connections.

In order to efficiently pool database connections from the application server,
most actions initiated via the web UI are run as the corresponding database user
role using the
[`SET ROLE` command](https://www.postgresql.org/docs/current/sql-set-role.html).
`SET ROLE` **does not** provide great insulation against privilege escalation.
**Queries which are not thoroughly validated and escaped must only be run via a
dedicated connection initiated with the user-level role's credentials.**

Given complete freedom it is possible, in fact easy, to configure a Postgres
table into what would be considered an "invalid" state by Phonograph, so table
creation and ownership is restricted to the "root" Phonograph role, which acts
on the behalf of the user in order to facilitate schema updates via the web
interface.

## Permissions Granted via User Roles

### Accessing workspace databases

`GRANT CONNECT ON <database> TO <role>;`

This permission is granted when initially creating the workspace, as well as
when accepting an invitation to a table.

Access to workspaces is controlled via the `CONNECT ON DATABASE` permission.
However, it is unreasonable to query every backing database to compute the set
of workspaces to which a user has access, so Phonograph caches workspace-level
"connect" permissions in its own centralized table (`workspace_memberships`).

`workspace_memberships` rows are added whenever the `GRANT CONNECT` command is
run, and are deleted after a `REVOKE CONNECT` command is run.

It is possible that an error occurs after `REVOKE CONNECT` but before the
membership record is deleted. Therefore for authorization purposes, membership
of a workspace is not a guarantee that the user has `CONNECT` privileges, just
that they might. In cases where the root Postgres user is fetching potentially
sensitive data on behalf of a user, the user's actual ability to connect to the
database should always be confirmed.

### Accessing the `phono` schema

`GRANT USAGE ON <schema> TO <role>;`

This permission is granted when initially creating the workspace, as well as
when accepting an invitation to a table.

## Creating, updating, and deleting columns

`GRANT <table owner role> TO <role>;`

This permission is granted when initially creating the table, as well as when
accepting an invitation to a table, if the invitation includes "owner"
permissions.

**This permission is only used via the web UI and must not be granted to service
credentials, lest users alter table structure in unsupported ways.**

### Reading table data

`GRANT SELECT ON <table> TO <role>;`

This permission is granted when initially creating the table, as well as when
accepting an invitation to the table.

Phonograph uses `SELECT` permissions to infer whether a table should be
accessible to a user via the web UI.

### Inserting rows

`GRANT INSERT (<columns>) ON <table> TO <role>;`

Write-protected columns (`_id`, etc.) are excluded.

This permission is granted when initially creating the table, as well as when
accepting an invitation to the table, if the invitation includes "edit"
permissions.

These permissions must be updated for each relevant user role whenever a column
is added; this is simplified by maintaining a single "writer" role per table.

### Updating rows

`GRANT UPDATE (<columns>) ON <table> TO <role>;`

Write-protected columns (`_id`, etc.) are excluded.

This permission is granted when initially creating the table, as well as when
accepting an invitation to the table, if the invitation includes "edit"
permissions.

These permissions must be updated for each relevant user role whenever a column
is added; this is simplified by maintaining a single "writer" role per table.

## Actions Facilitated by Root

- Creating tables

## Service Credentials

Direct user PostgreSQL connections are performed using secondary `LOGIN` roles
created by the user's primary workspace role (where the primary workspace role
is e.g. `usr_{user_id}`). The credentials for these secondary roles are referred
to as "service credentials" or "PostgreSQL credentials". Service credentials are
created and assigned permissions by users in the web UI, and their permissions
are revoked manually in the web UI and/or by cascading `REVOKE` commands
targeting the primary workspace role.

Service credential role names have the format
`svc_{user_id}_{8 chars (4 bytes) of random hex}`. With the user ID consuming 32
characters, this balances name length with an ample space for possible names.

# Copyright and License

All original source code in this repository is copyright (C) 2025 Second System
Technologies LLC and distributed under the terms in
[the "LICENSE" file](./LICENSE). Certain third-party assets within
[the "static" directory](./static) may be governed by different licenses, for
example the Open Font License or MIT License, as stated by their original
authors. Copies of each relevant license have been included alongside these
files as needed.

# Footnotes

[^1]:
    Barring historical pedantry, "Postgres" and "PostgreSQL" are essentially
    synonymous and are often used interchangeably. As a matter of convention
    throughout Phonograph docs, "Postgres" is largely used to refer to the
    database software, while "PostgreSQL" is typically used to refer to the
    query language and/or wire protocol.