auth

Install durable users, sessions, and the auth Console surface.

Install auth when the host needs durable users and sessions for application login, Runtime Console access, or both.

From a generated host:

lenso module install auth
cargo run --bin migrate
lenso serve

The CLI updates host composition, dependencies, local install receipts, and the Runtime Console extension registry. Restart the API and worker after installing or updating modules.

User model

auth.users is the shared authentication anchor. Business routes and Runtime Console both resolve to the same ActorContext::User { user_id, scopes }.

Keep product profile data in your own tables and key it by the auth user id:

create table app.profiles (
    id text primary key,
    auth_user_id text not null unique,
    display_name text not null,
    created_at timestamptz not null
);

Do not add name, avatar, plan, tenant, or organization fields to auth.users. Those belong to the product module. If your product needs different account ids, store a mapping from the account row to auth_user_id.

After restart, verify:

• /console lists auth under Modules.
• Data shows Auth users and sessions.
• Actions include session revoke and user enable or disable actions.

Console identities are separate

The independent Lenso Console owns its own Auth domain and Service Store. A business Service user does not automatically become a Console Operator, and the Console must not read or write this host’s Auth tables. Initialize the first Console Operator with lenso console operator bootstrap; manage later Operators through the Console’s identity Module. Development bearer tokens are local-only.

Use Redis session lookup

Postgres is the default session lookup backend. Use Redis when session reads should avoid a database hit:

lenso module install auth --profile redis-session-cache

The profile enables the redis feature for lenso-module-auth, writes REDIS_URL=redis://localhost:6379/0 to .env, and records auth.session_cache=redis in .lenso/runtime-config-defaults.json.

Provide Redis yourself. The starter Docker Compose file starts Postgres only.

Development sessions

In local development, auth exposes a dev-session route:

curl -sS -X POST http://127.0.0.1:3000/v1/auth/dev/sessions \
  -H 'content-type: application/json' \
  -d '{"user_id":"usr_demo"}' | jq .

Use the returned token as a bearer token:

curl -sS http://127.0.0.1:3000/v1/app/items \
  -H "authorization: Bearer $LENSO_SESSION_TOKEN" | jq .

For quick local work, generated hosts also accept development bearer tokens such as Bearer dev-user:usr_demo. Do not use those in production.

Manual Rust composition

Most hosts should use lenso module install. For hand-written host composition, use the public builtins exposed by the host feature:

use lenso::host::prelude::*;

pub fn host_composition() -> HostComposition {
    HostBuilder::new()
        .linked_module(builtins::auth())
        .build()
}

Run migrations after changing linked module composition:

cargo run --bin migrate