@nan0web/auth.app

Authentication & Authorization micro-application for the nan•web ecosystem.

🇺🇦 Українська версія

One Logic — Many UI: a single core (AuthApp) powers CLI, HTTP API, and Web Component interfaces without code duplication.

Features

| Feature | Status | |---------|--------| | Sign Up (email + username + password) | ✅ | | Confirm Sign Up (contact + code) | ✅ | | Login (identifier + password) | ✅ | | Forgot Password / Reset Password | ✅ | | Update Info (authorized) | ✅ | | Token Refresh + Rotation | ✅ | | Soul ID Linking (sun.app bridge) | ✅ | | Community Membership Registration | ✅ | | Interactive CLI (ui-cli) | ✅ | | REST API Server (ui-api) | ✅ | | Web Components (ui-lit) | 🔧 WIP |

Architecture

graph TD
    A[AuthApp — agnostic core] --> B[ui-cli — Terminal]
    A --> C[ui-api — REST / HTTP]
    A --> D[ui-lit — Web Components]

• AuthApp — pure business logic as async generators (yield messages)
• ui-cli — interactive terminal using @nan0web/ui-cli (Select, Forms)
• ui-api — domain-driven HTTP router via @nan0web/http-node
• ui-lit — Lit-based <auth-login-form> Web Component

App-in-App Integration

graph LR
    R[register.js] -->|api| HOST_API[Host Router]
    R -->|cli| HOST_CLI[Host CLI]
    R -->|service| HOST_SVC[AuthApp Factory]
    HOST_API --> SUN[sun.app]
    HOST_API --> BANK[bank.app]
    HOST_CLI --> SUN
    HOST_SVC --> SUN

Any nan•web application can embed auth.app via register(): it receives ready-made API routes, CLI commands, and a service factory.

User Journey

flowchart TD
    START((User)) --> SIGNUP[Sign Up]
    SIGNUP --> CONFIRM[Confirm Sign Up]
    CONFIRM --> LOGIN[Login]
    START --> LOGIN
    LOGIN --> TOKEN{Token}
    TOKEN --> UPDATE[Update Info]
    TOKEN --> REFRESH[Refresh Token]
    TOKEN --> LINK_SOUL[Link Soul ID]
    TOKEN --> REG_COMMUNITY[Register for Community]
    START --> FORGOT[Forgot Password]
    FORGOT --> RESET[Reset Password]
    RESET --> LOGIN
    TOKEN --> AUTH[Authenticate by Token]

Installation

pnpm add @nan0web/auth.app

CLI Usage

# Interactive mode — select action from menu
pnpm cli

# Direct command execution
pnpm cli signup
pnpm cli confirm
pnpm cli login

# Show help
pnpm cli --help

Available commands: signup, confirm, login, forgot, reset, info, refresh

API Server

# Start the HTTP server on port 3000
pnpm api

Example request:

curl -X POST http://localhost:3000/api/Auth/LogIn \
  -H "Content-Type: application/json" \
  -d '{"username":"test", "password":"secret"}'

The API router auto-generates routes from the domain message tree.

Programmatic Usage

Core (direct)

import AuthApp from '@nan0web/auth.app/src/AuthApp.js'

const app = new AuthApp({ db, tokenManager, logger, tokenRotationRegistry })
await app.init()

// All actions return async generators
for await (const msg of app.signUp({ body: { email, username, password } })) {
  console.log(msg.content)
}

App-in-App Registration

import register from '@nan0web/auth.app/src/register.js'

const setup = register.register({
  api: { prefix: 'my-auth' },
  cli: { command: 'users' }
})

// setup.api    — REST routes integration
// setup.cli    — CLI command integration
// setup.service — AuthApp factory

Sun.app Bridge

// Link a sovereign Soul ID to a local user
for await (const msg of app.linkSoulId({ body: { username, soulId } })) {
  console.log(msg.content)
}

// Register + join community in one step
for await (const msg of app.registerForCommunity({
  body: { email, username, password, soulId, communityId }
})) {
  console.log(msg.content)
}

Messages (Domain Model)

| Message | Purpose | Key Fields | |---------|---------|------------| | SignUpMessage | New user registration | email, username, password | | ConfirmSignUpMessage | Email/phone confirmation | contact, code | | LoginMessage | User authentication | identifier, password | | UpdateInfoMessage | Profile update (authorized) | username, avatar, bio | | AuthorizedMessage | Base for authorized actions | authorization header | | RegistrationMessage | Internal registration flow | email, username, password, soulId |

All messages extend @nan0web/co/Message and define a static Body schema with validation, labels, placeholders and type metadata.

Dependencies

| Package | Role | |---------|------| | @nan0web/co | Core framework (App, Message, OutputMessage) | | @nan0web/auth-core | Access control, Membership rules | | @nan0web/auth-node | AuthDB, TokenManager, TokenRotationRegistry | | @nan0web/ui-cli | Interactive CLI components (Select, Form, etc.) | | @nan0web/ui | UiForm abstraction | | @nan0web/http-node | HTTP Server and Router | | @nan0web/log | Logger |

Scripts

| Script | Description | |--------|-------------| | pnpm test | Run unit tests (85+ tests) | | pnpm test:all | Full pipeline: test → docs → build → knip → audit | | pnpm test:docs | Generate README.md from source | | pnpm build | TypeScript type-check (tsc) | | pnpm cli | Launch interactive CLI | | pnpm api | Start API server | | pnpm knip | Dead code analysis |

Contributing

1. Clone the monorepo: git clone https://github.com/nicoth-in/nan.web.git
2. Install dependencies: pnpm install
3. Run tests: pnpm test:all
4. Follow the nan•web Engineering Standards

License

ISC