auth

Install the host-owned authentication anchor for users, identities, and sessions.

Install auth when the Host needs durable users and sessions for application login. It is the anchor required by every other official auth method.

From a generated host:

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

The CLI updates Host composition, dependencies, and local install receipts. Restart the API and worker after installing or updating modules.

User model

auth.users is the shared authentication anchor. Authenticated business routes resolve to 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, use the connected Console’s Modules view to verify that auth is loaded. Its Console surface exposes users, sessions, session revocation, and user enable or disable operations to an authorized operator.

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