# Identity and sessions

Routed from `skills/SKILL.md`. The authoritative operation list is
[api-reference.md](api-reference.md); nothing below adds to it.

## What is served

Three identity operations and two session operations:

- `bun.identity.register` — create a principal.
- `bun.identity.login` — authenticate and obtain a session.
- `bun.identity.current` — read the current principal.
- `bun.session.validate` — validate a session token.
- `bun.session.revoke` — revoke a session.

Credentials are a separate family: `bun.credential.issue`,
`bun.credential.validate`, `bun.credential.rotate`, `bun.credential.revoke`,
`bun.credential.describe`.

## What is not served

Lines marked `NOT-SERVED:` are verified absent from the registry by the guard
test, so this list cannot quietly become wrong.

NOT-SERVED: `bun.identity.logout` `bun.identity.list` `bun.identity.delete`
NOT-SERVED: `bun.identity.reset_password` `bun.identity.enroll_mfa`
NOT-SERVED: `bun.session.list` `bun.session.refresh`

Session teardown is `bun.session.revoke`. Do not synthesise the rest.

## Notes that change how you write code

- `bun.identity.register`, `bun.identity.login`, `bun.identity.current` and
  `bun.session.validate` declare `requires_auth: no`, because each establishes or
  checks its own subject. That is not a permission bypass.
- None of the identity or session operations requires tenant context. Tenant
  membership is a separate concern — see [tenants.md](tenants.md).
- Identity providers are pluggable (`backend/app/identity/`), and the fake
  provider is labelled non-production. It stays that way.
- **Identity is the one provider category whose switch is `GUIDED`, not
  automated**, because password hashes cannot be exported between providers.
  See [switching.md](switching.md).