atlas-node-admin

Summary

atlas-node-admin is a library-only admin/backoffice API crate that atlas-node can embed when the demo-admin-apis feature is enabled. It exposes admin routes for account and institution operations, KYC issuance and registration helpers, and a workflow system for KYC/alias review backed by SQLite plus filesystem-stored evidence blobs.

This crate is not a standalone service by itself today. It is started from atlas-node, and its runtime shape is tightly coupled to the node's demo/admin mode.

Why This Crate Exists

• expose admin-only HTTP routes without mixing them into the public REST surface
• support validator-authenticated review flows for KYC and alias requests
• persist KYC workflow state outside the ledger in a simpler operational store
• help convert approved KYC/admin actions into signed transactions submitted to the mempool
• provide wallet-import/share-link flows for portable KYC artifacts

Current Role In The Workspace

atlas-node-admin currently owns five related concerns:

1. admin API routing and Axum state assembly
2. validator challenge/session authentication for reviewer access
3. KYC issuance and registration helpers around PortableKyc
4. workflow persistence for KYC applications, alias requests, evidence blobs, and wallet-import links
5. institution/account admin endpoints that turn admin actions into mempool submissions or in-memory registry changes

This crate is broader than "just admin routes". It is really an admin API plus a lightweight workflow/backoffice subsystem.

Public Surface

Top-Level Modules

• auth
• internal dtos
• internal handlers
• internal workflow

Main Public Reexports

• WorkflowStore
• IssueKycRequest
• IssueKycResponse
• KycPayloadRequest
• RegisterAliasRequest
• RegisterAliasResponse
• RegisterKycProofRequest
• RegisterKycProofResponse

Important Types

• AdminAppState
• WorkflowStore
• auth::ValidatorAuthStore
• auth::ValidatorSession
• workflow::KycApplicationRecord
• workflow::AliasRequestRecord
• workflow::EvidenceBlobRecord
• workflow::KycWalletImportLinkRecord
• workflow::ReviewStatus

Package Targets

• library target atlas_node_admin
• no standalone binary target in this package today

Key Modules

• `lib.rs`: admin router, app state, route registration, CORS/body-limit setup, and server startup
• `auth.rs`: validator challenge/session flow and validator-KYC gatekeeping
• `workflow.rs`: SQLite-backed workflow persistence plus evidence directory management
• `handlers/kyc.rs`: portable KYC issuance, KYC proof registration, and alias-registration helper flow
• `handlers/workflow.rs`: KYC and alias workflow endpoints, evidence upload, approvals, and wallet-import links
• `handlers/institutions.rs`: institution mint/issue endpoints
• `handlers/accounts.rs`: account open and reclassification triggers
• `dtos.rs`: small response DTOs

Inputs And Outputs

Inputs

• Ledger, Mempool, and AccountRegistry injected from atlas-node
• workflow database path and evidence directory on disk
• configured issuer address/secret and minimum validator-KYC threshold
• validator wallet auth headers or bearer session tokens
• KYC applications, evidence uploads, alias requests, and review decisions
• signed transactions that need fee-payer/admin attachment before mempool submission

Outputs

• an admin Axum router mounted separately from the public REST API
• in-memory validator sessions and challenges
• SQLite records for KYC/alias workflow state
• filesystem-stored evidence blobs
• signed transactions submitted into the mempool
• portable KYC artifacts and wallet-import/share-link envelopes

Internal Dependencies

Workspace Dependencies

• atlas-common
• atlas-ledger
• atlas-mempool
• atlas-bank
• atlas-kyc

This crate sits above both domain and infra crates, but below the atlas-node executable that hosts it.

External Dependencies That Shape The Design

• axum for the embedded admin HTTP API
• rusqlite for workflow persistence
• tokio for async file and server work
• ed25519-dalek, sha2, and hex for session/auth and portable-KYC related verification

Used By

atlas-node is currently the only direct crate-level consumer:

• `Cargo.toml`: optional dependency behind demo-admin-apis
• `main.rs`: builds AdminAppState, opens WorkflowStore, and starts start_admin_api(...)

Operationally, this admin surface shows up only when the node is started in demo/admin mode:

• `start_demo_dev.sh`: builds atlas-node with demo-admin-apis,unsafe-demo
• `start_demo_prod.sh`: same pattern for the production-style demo launcher
• `docker/supervisord.conf`: injects ATLAS_ADMIN_* env vars into node processes
• `docs/dev/docker.md`: describes the admin API as loopback-only behind Nginx in the demo stack

API Model

Router Shape

build_admin_router(...) in `lib.rs` registers a mixed surface that currently includes:

• account reclassification
• account opening
• institution issue/mint
• validator session challenge and completion
• KYC issue/register-proof/register-alias helpers
• KYC workflow submission, listing, approval, rejection, and evidence handling
• alias request submission, listing, approval, and rejection
• portable-KYC wallet import/share-link flows

This is important: not every route is protected the same way.

Three Access Patterns Exist

The current admin surface splits into three rough categories:

1. validator-reviewed routes guarded by require_validator_session(...)
2. self-service/user-submission routes with no validator session
3. issuer-configured routes that rely on configured issuer wallet/secret rather than bearer session auth

Examples of validator-session protected routes:

• listing all KYC applications
• approving or rejecting KYC applications
• listing all alias requests
• approving or rejecting alias requests

Examples of self-service/public workflow routes:

• submit KYC application
• upload evidence
• list KYC applications by wallet
• submit alias request
• list alias requests by wallet
• create wallet-import share link
• redeem/get wallet-import share link with signed headers

Examples of issuer-configured helper routes:

• POST /api/kyc/issue
• POST /api/kyc/register-proof
• POST /api/kyc/register-alias

Validator Auth Model

The validator-auth flow in `auth.rs` is challenge/response based:

1. create_validator_challenge_api creates a short-lived challenge message
2. the wallet signs that challenge
3. complete_validator_session_api verifies the signature and creates a bearer session token
4. protected routes call require_validator_session(...)

Two extra constraints are central here:

• the session must match the configured issuer/validator wallet
• that wallet must hold at least min_validator_kyc_balance of the system KYC token

This makes the validator session gate not only cryptographic, but also balance-gated.

Workflow And Persistence Model

WorkflowStore in `workflow.rs` is the crate's biggest subsystem.

Persistent Data

It creates and manages four SQLite tables:

• kyc_applications
• alias_requests
• evidence_blobs
• kyc_wallet_import_links

In parallel, it also maintains an evidence blob directory on disk next to the database.

In-Memory View

At open time, the store loads:

• kyc_applications into an in-memory BTreeMap
• alias_requests into an in-memory BTreeMap

Evidence blobs and wallet-import links are still fetched from SQLite on demand instead of being fully cached in memory.

Workflow Semantics

The KYC workflow model stores:

• requester wallet
• entity type and requested verification level
• form data
• attachments and liveness payloads
• review status
• optional approved PortableKyc
• optional evidence manifest and reviewer notes

The alias workflow model stores:

• alias and alias kind
• requester wallet
• raw request payload
• review status
• optional approval permit signed by a validator

KYC And Alias Flow

Portable KYC Issuance

`issue_kyc_api(...)` issues a PortableKyc envelope using either:

• configured issuer credentials from AdminAppState
• or issuer credentials provided in the request

The route still requires the issuer wallet to satisfy the validator-KYC minimum.

Registering Proof And Alias

`register_kyc_proof_api(...)` verifies the portable KYC, derives a proof hash, validates that the provided RegisterKyc transaction matches it, attaches fee-payer/admin signing, and submits the signed transaction to the mempool.

`register_alias_api(...)` similarly fee-payer-signs a RegisterKyc plus RegisterAlias pair and submits them to the mempool in order.

Workflow Review

The workflow approval side in `handlers/workflow.rs` does not itself write to the ledger. It stores review outcomes and artifacts:

• approving a KYC application persists the approved PortableKyc onto the workflow record
• approving an alias request persists a signed AliasApprovalPermit

That means this crate acts as a review/control plane first, and only some routes actually convert actions into mempool transactions.

Institution And Account Admin

Institution Issue And Mint

`issue_tokens_api(...)` and `mint_tokens_api(...)` both derive an institution admin signing key, verify the claimed operator address, compute a free nonce in the issuance vault, sign a transaction, and submit it to the mempool.

The current semantics are:

• issue transfers from vault:{institution_id}:issuance to a destination wallet
• mint currently also builds a signed transfer, but back into the same vault account

The implementation is clearly tailored to the current institutional issuance model and demo setup.

Account Endpoint

`create_account_api(...)` uses atlas_bank::AccountService over the injected AccountRegistry plus ledger institutions. It validates and registers the account in that registry, but it does not directly emit a ledger transaction.

That makes it materially different from the institution/KYC mempool-submission routes.

Wallet Import Link Flow

One specialized workflow in `handlers/workflow.rs` is the portable-KYC wallet import/share-link path.

The current flow is:

1. user creates a share link for an approved KYC application using wallet-signed metadata
2. the server persists a KycWalletImportLinkRecord
3. the consumer redeems the link by presenting signed headers
4. the server returns a KycWalletImportLinkEnvelope containing the portable KYC

So this crate is also acting as a controlled handoff point for KYC portability between client apps.

Testing

The crate currently relies on module-local tests rather than package-level integration tests.

Observed direct test coverage includes:

• admin router shape in `lib.rs`
• KYC handler flows in `handlers/kyc.rs`
• institution issue/mint flows in `handlers/institutions.rs`

There does not appear to be equally direct test coverage for every auth/workflow path yet.

Risks Or Design Tension

Not Every "Admin" Route Is Protected The Same Way

The crate mixes:

• validator-session protected review routes
• publicly callable submission routes
• issuer-secret based helper routes

That may be the right product choice, but it means "admin API" is not one single trust boundary.

Validator Sessions Are In-Memory Only

ValidatorAuthStore keeps challenges and sessions in memory only. A process restart invalidates all active sessions, and there is no shared/session-persistent backing store today.

Workflow State Lives Outside The Ledger

Approvals, evidence, share links, and review notes live in SQLite/filesystem state, not in the ledger. That is operationally pragmatic, but it creates a separate source of truth for admin workflow state.

`create_account_api` Looks Non-Durable

The account-open path currently writes into the injected AccountRegistry, which is an in-memory bank-domain registry, not a ledger-backed persistence path. That makes it behave differently from the transaction-submission routes and may limit its durability across restarts.

Institution Admin Keys Look Demo-Oriented

The institution handlers derive admin signing keys from hardcoded demo seeds for known institutions, and fall back to deterministic hashing for others. That is convenient for demos, but it is a strong sign that this part of the crate is still shaped by non-production assumptions.

Feature-Gated Hosting Hides The Crate

Because this crate has no standalone binary and is only hosted by atlas-node behind demo-admin-apis, it is easy for the code to drift without being part of the mainline node runtime in every environment.