Library users, sign-in, and permissions

Library users, sign-in, and permissions

Current PhotoStructure releases have no built-in sign-in screen. Keep them on a trusted computer or private network, or protect them with a VPN or an authenticated reverse proxy. See remote access for the current options.

The planned access controls add passwordless sign-in without making the first person who reaches your server its owner.

Three mutually exclusive modes

Each library uses exactly one configured mode:

  • none serves the ordinary library without sign-in.
  • email signs in enrolled users with typed six-digit email codes.
  • oidc signs in enrolled users through one OpenID Connect provider.

Email and OIDC are never offered together. Changing modes is a local deployment operation followed by a restart, not a switch on the owner settings page.

Missing, invalid, conflicting, or incomplete configuration puts PhotoStructure in a derived state called authSetupRequired. This is not a fourth mode and is not a valid value for PS_AUTH_MODE. PhotoStructure shows a fixed setup explanation instead of photos, settings, logs, or library actions.

Network exposure never chooses a mode. A Docker published port, LAN address, loopback address, reverse proxy, or request source IP is not permission to serve a library without sign-in.

Safe first-owner setup

An email or oidc library needs at least one owner whose identity works with that mode. Upgraded libraries need the same step because an older library has no trusted user identity to promote.

Docker uses environment configuration as its auth control plane. Before the first owner exists:

  • one valid PS_BOOTSTRAP_OWNER_EMAIL, complete email delivery configuration, and no explicit mode selects email;
  • PS_AUTH_MODE=oidc requires that same singular bootstrap email and one complete provider configuration; and
  • serving without sign-in requires explicit PS_AUTH_MODE=none with no bootstrap email.

PS_BOOTSTRAP_OWNER_EMAIL selects one provisional first-owner identity. It is not an owner list. After bootstrap, changing it cannot add, remove, relink, or restore an owner.

In email mode, the selected inbox proves identity with a six-digit code. In OIDC mode, the provider must return that exact normalized email with a true email_verified claim during the first login. PhotoStructure then identifies the owner by the provider’s stable (issuer, subject) pair.

Desktop will collect the same decisions through a native setup window. Node will use local configuration or an operator-invoked local command. There is no setup claim code, startup trust window, source-IP shortcut, or remote first-writer flow.

The exact provider fields, delivery settings, Node command, and Desktop screens are still under construction. Do not copy the setting fragments above into a current deployment as setup instructions.

Upgrading an existing library

A fresh or upgraded library without complete valid auth configuration pauses ordinary web access in the release that adds this feature. Your media and library metadata stay unchanged.

The local operator chooses one path:

  • configure email, prove the singular bootstrap inbox, and create the first owner;
  • configure oidc, prove the matching provider identity, and create the first owner; or
  • explicitly configure none and restart PhotoStructure.

The locked page will include the minimum tested recovery steps, so recovery does not depend on this website or DNS being available.

Signing in with email codes

In email mode, an enrolled user enters an email address and receives a short-lived, single-use six-digit code. Requesting a code never enrolls a new library user. Unknown and disabled addresses receive the same public response and no usable challenge.

The operator chooses one delivery method:

  • PhotoStructure’s hosted relay, available to LITE and PLUS; or
  • an operator-configured SMTP server, available to LITE and PLUS.

The relay can send only a fixed challenge to the address PhotoStructure chose. It cannot create users, assign roles, verify codes, or create a session. LITE may have a lower aggregate hosted-service allowance, but its per-address security limits and built-in authentication are the same as PLUS.

Passwords and magic links are not part of the first release.

Signing in with OIDC

In oidc mode, PhotoStructure asks one configured provider, such as Keycloak, to prove who signed in. The provider proves identity; PhotoStructure decides whether that identity is enrolled and what it may do.

PhotoStructure identifies an OIDC user by the exact provider issuer and stable subject identifier. It does not link identities merely because email addresses match. Provider roles and groups cannot grant a PhotoStructure role.

See single sign-on for the planned OIDC contract.

Roles

Each enrolled user has one library-wide role:

RoleWhat it permits
VisitorBrowse the library without changing asset or library metadata.
ContributorVisitor access plus library curation, including ratings, asset metadata, tags, and albums.
OwnerContributor access plus user, settings, health, diagnostics, sync, and library-wide administration.

There is no separate admin role. /admin/** names a privileged part of the website, not a role.

An owner enrolls one exact email and assigns its local role. In OIDC mode, the first matching verified provider login binds that enrollment to (issuer, subject). Unknown identities do not self-register and never receive a default visitor role.

Ordinary administration cannot disable, demote, delete, or disconnect the last owner who can sign in through the active mode.

A future view-only link will be a limited sharing link, not a user role. Following one will not turn someone into a library visitor or open the rest of the library.

Changing modes and recovering access

Even a signed-in owner cannot turn authentication off, replace the OIDC provider, switch libraries, or start lost-owner recovery through an ordinary web request. Those operations require local control of Docker, Node, or the Desktop host process.

There is no standing recovery code or setup claim. A deliberately invoked local recovery operation selects one exact recovery email. That inbox must still complete normal code proof before PhotoStructure creates or restores a usable owner. The exact recovery command and Desktop action will be documented after they exist. Editing the database is not a supported recovery path.

What travels with a library

Users, local roles, and identities belong to the library. Live sessions, delivery credentials, OIDC client secrets, login challenges, and recovery transactions stay with the deployment and do not travel in a normal library archive.

Docker ignores copied TOML auth mode, bootstrap email, and provider configuration. A copied Docker library cannot open without its destination’s own environment configuration, including explicit PS_AUTH_MODE=none when sign-in is disabled.

Desktop and Node may persist the selected mode with the library. Moving or copying that complete library carries the mode by design.

Security limits

  • Built-in sign-in protects PhotoStructure’s web interface. It does not encrypt files or isolate someone who has equivalent host, Docker-daemon, configuration, operating-system account, or Desktop-session control.
  • Every non-loopback deployment declares its exact browser origin with PS_EXTERNAL_ORIGIN. Email and OIDC require HTTPS. An explicit none deployment may use HTTP only after a strong privacy warning.
  • Exact loopback Desktop and loopback-only Node are the only planned plain-HTTP sign-in profiles. A reverse proxy forwarding to 127.0.0.1 is an external deployment and does not qualify.
  • Authentication and local roles are available to both LITE and PLUS.

See also