Metadata-Version: 2.4
Name: splent_feature_identities
Version: 0.1.0
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: Authlib==1.6.12
Dynamic: license-file

# splent_feature_identities

The `identities` feature of a [SPLENT](https://splent.io) product line.

The accounts on sign-in providers (ORCID, GitHub...) that people link to
their account. It keeps one row per linked provider account, lists them at
`/account/identities`, lets the owner disconnect one, and holds the
product's one OAuth registry, which every provider feature registers its
client on. It shows nothing on its own. A provider feature (orcid, github)
brings the buttons and the rows. It needs `auth`, which owns the accounts,
and `profile`, whose edit page is where the linked accounts are managed.

A SPLENT feature is a Python package that a product composes with others.
Its models, routes, services, templates and hooks are registered when the
product starts. What this feature provides and requires is listed in the
`[tool.splent.contract]` section of `pyproject.toml`, which
`splent feature:contract --write` keeps in sync with the source.

## The rules every provider follows

`IdentitiesService` holds them, so ORCID and GitHub behave the same way.

| Rule | How |
|---|---|
| A provider account signs in to the account it is linked to | `linked_user(provider, provider_id)` |
| A sign-in never joins an existing account because an email matches, since nothing proves the person owns that address | `email_in_use(email)` covers accounts and other providers' rows |
| Linking happens from inside the account, through the provider's connect flow | `add_identity(...)` while signed in |
| Disconnecting is for the owner only | `disconnect(user, provider, provider_id)` returns False for someone else's |
| A sign-in opens a new account only when the product installs signup | `registration_is_open()`, and `closed_registration_message(provider)` for the refusal |

After a disconnect it sends `identity-disconnected` with `user`, `provider`
and `provider_id`, so the provider feature drops what it keeps of its own.

## Closed products

A product that does not install `splent_feature_signup`, the optional
feature that opens registration, is closed, and an administrator opens its
accounts. A provider must not be a way around that. Before it creates an
account it asks `registration_is_open()`, which is true only when signup's
blueprint is registered, and in a closed product it refuses with
`closed_registration_message(provider)` instead.

| Visitor | Product with signup | Product without signup |
|---|---|---|
| Signs in with a provider account already linked | Signed in | Signed in |
| Connects a provider from inside their account | Linked | Linked |
| Signs in with a provider account linked to nobody | A new account is opened | Refused, and told to ask an administrator for access or to connect the provider from their profile |

The message names no account and no address, so in a closed product the
refusal tells a stranger nothing about who has an account. It is translated,
and it reads "New accounts are opened by an administrator, so signing in with
ORCID cannot create one. Ask an administrator for access. If you already have
an account, sign in as usual and connect ORCID from your profile."

```python
from splent_io.splent_feature_identities.services import IdentitiesService

identities = IdentitiesService()
if not identities.registration_is_open():
    return None, identities.closed_registration_message("MyProvider")
```

## Settings

| Setting | Default | What it does |
|---|---|---|
| `EXTERNAL_LOGIN_PASSWORD_HINT` | false | After a wrong email or password on the login page, names the providers the account signs in with |

An account opened through a provider has no password its owner knows, so a
wrong password is the expected outcome there. With the hint on, auth's
"Invalid credentials" is followed by "This account signs in with ORCID.
Continue with it below." It is off by default because it tells whoever types
an address that an account exists for it and how it signs in. A product
whose accounts are public anyway (a repository that lists its authors)
turns it on.

```toml
[tool.splent.config]
EXTERNAL_LOGIN_PASSWORD_HINT = true
```

Only a wrong email or password gets the hint. auth renders its
`auth.login.error_hint` slot for that case alone, never for a throttled
attempt or an account that is not active yet.

## Adding a provider

A provider feature registers its OAuth client on the shared registry and
draws itself in the slots auth, signup and profile open. Each callback takes
no arguments and returns HTML, or an empty string to add nothing.

| Slot | Opened by | What a provider puts there |
|---|---|---|
| `auth.login.providers` | auth | Its sign-in button, under "or continue with" |
| `signup.providers` | signup, when the product has it | The same button, after the sign-up form |
| `profile.edit.sections` | profile | Its row, with the linked account and a disconnect button or a connect link |

```python
# services.py of a provider feature
from splent_io.splent_feature_identities.oauth import oauth_for


def register_myprovider_client(app):
    oauth_for(app).register(name="myprovider", client_id=..., client_secret=...)
```

```python
# hooks.py of the same feature
from splent_framework.hooks.template_hooks import register_template_hook

register_template_hook("auth.login.providers", sign_in_button, order=30)
register_template_hook("signup.providers", sign_in_button, order=30)
register_template_hook("profile.edit.sections", linked_account_row, order=30)
```

The disconnect button of a row opens this feature's modal, which is drawn
once on the edit-profile page and posts to
`/account/disconnect/<provider>/<provider_id>`.

```html
<button type="button" data-bs-toggle="modal" data-bs-target="#disconnectModal"
        data-provider="myprovider" data-provider-id="{{ identity.provider_id }}">
```

GitHub takes order 10 and ORCID 20 in all three slots.

## Translations

The login hint and the closed registration message ship with a Spanish
catalog.

## Use it in a product

```bash
splent feature:add splent_feature_identities
```

## Develop

```bash
splent feature:test splent_feature_identities
splent feature:contract splent_feature_identities
```

## Release

```bash
splent feature:release splent_feature_identities --dry-run --bump patch
splent feature:release splent_feature_identities
```

The first command rehearses the release and changes nothing. The second
publishes it to the git forge and to PyPI, and a PyPI version is permanent.
