# Public API Audit
This document inventories the current public surface of `nythos-core`, including the implemented `v0.2.0` identity profile and login identifier work.
It records what looks intentionally public today and what should be revisited only in a later explicit API cleanup window.
The `v0.2.0` identity profile work adds public domain types and updates service
and port signatures. Compatibility notes below call out preserved constructors
and source-breaking adapter-facing changes.
## High-level Summary
- The crate root already provides a coherent ergonomic surface through `src/lib.rs` re-exports.
- The `auth`, `domain`, and `ports` module roots also expose curated re-export surfaces.
- The strongest accidental exposure risk is deeper implementation-shaped module paths and a few public constructors on output/result wrappers, not the crate-root export list itself.
## Path Layering Today
- `nythos_core::*` exposes selected crate-root re-exports from `src/lib.rs`.
- `nythos_core::auth::*`, `nythos_core::domain::*`, and `nythos_core::ports::*` expose additional module-root re-exports.
- Because several internal files are also declared with `pub mod`, deeper paths are public today too. Example: `nythos_core::auth::register::RegisterService`.
- `nythos_core::rbac`, `nythos_core::session`, and `nythos_core::error` are direct public modules without another re-export layer inside them.
## Crate-root Exports
Unless noted otherwise, each item below is available at `nythos_core::<Item>` and also through its area-specific module root.
### auth
| `AccessToken` | intentionally public | Core signed-token value used by `TokenSigner`, auth flow outputs, and callers inspecting issued auth material. |
| `Claims` | intentionally public | Structured claim set used by signing and verification boundaries. |
| `LoginAuthMaterial` | intentionally public | Direct login-flow output returned to callers. |
| `LoginInput` | intentionally public | Callers construct this to run login orchestration; it now stores a raw identifier internally. |
| `LoginService` | intentionally public | Main login orchestration entry point. |
| `PasswordHash` | intentionally public | Required by `PasswordHasher`, `UserRepository`, and credential-loading boundaries. |
| `RefreshAuthMaterial` | intentionally public | Direct refresh-flow output returned to callers. |
| `RefreshInput` | intentionally public | Callers construct this to run refresh orchestration. |
| `RefreshService` | intentionally public | Main refresh orchestration entry point. |
| `RegisterAuthMaterial` | intentionally public | Returned from `RegisterResult` when auto-sign-in is enabled. |
| `RegisterInput` | intentionally public | Callers construct this to run registration orchestration; it accepts optional raw profile fields. |
| `RegisterResult` | intentionally public | Register-flow return type exposed directly to callers. |
| `RegisterService` | intentionally public | Main registration orchestration entry point. |
| `RevokeAllSessionsInput` | intentionally public | Callers construct this to revoke all sessions for a tenant-scoped user. |
| `RevokeAllSessionsService` | intentionally public | Main revoke-all orchestration entry point. |
| `RevokeResult` | likely intentionally public | Service return wrapper is part of the public flow API, even if its constructor may be broader than needed. |
| `RevokeSessionInput` | intentionally public | Callers construct this to revoke one session. |
| `RevokeSessionService` | intentionally public | Main revoke-one orchestration entry point. |
| `TokenPurpose` | likely intentionally public | Exposed through `Claims` and token verification, but currently has only one variant and lower direct usage pressure than the rest of the auth surface. |
### domain
| `Email` | intentionally public | Core validated value object used by callers and port implementations. |
| `Username` | intentionally public | Normalized lowercase ASCII lookup identifier used by user profile and optional username login. |
| `DisplayName` | intentionally public | Human-readable profile label; not used for login lookup. |
| `LoginIdentifier` | intentionally public | Typed login identifier enum over email and username. |
| `Password` | intentionally public | Required by the public `PasswordHasher` boundary. |
| `RoleId` | intentionally public | Tenant-scoped RBAC identity used in public domain and port APIs. |
| `SessionId` | intentionally public | Required by session, revocation, and port APIs. |
| `Tenant` | likely intentionally public | Public identity model carrying slug, optional settings, and auth policy. |
| `TenantId` | intentionally public | Required by domain models, services, and port traits. |
| `TenantAuthPolicy` | intentionally public | Typed auth policy embedded in `Tenant` and loaded by auth services. |
| `TenantSettings` | likely intentionally public | Public because `Tenant` exposes it directly, but it is lower-pressure than the auth/session/RBAC core types. |
| `User` | intentionally public | Central domain identity returned by flows and used by repositories. |
| `UserId` | intentionally public | Required across domain models, services, and repositories. |
| `UserStatus` | intentionally public | Returned by `User` and used by `UserRepository::update_status`. |
### error
| `AuthError` | intentionally public | Shared failure type for the entire public API. |
| `NythosResult` | intentionally public | Standard result alias used across the crate's public surface. |
### ports
| `NewUser` | intentionally public | Helper payload required by `UserRepository::create`. |
| `PasswordHasher` | intentionally public | Adapter-facing trait implemented outside the crate. |
| `RefreshTokenRotation` | intentionally public | Helper payload required by `SessionStore::rotate_refresh_token`. |
| `RevocationChecker` | intentionally public | Adapter-facing trait used by refresh and request-time enforcement. |
| `RoleAssignmentInput` | intentionally public | Helper payload required by `RoleRepository` assignment methods. |
| `RoleRepository` | intentionally public | Adapter-facing trait implemented outside the crate. |
| `SessionRecord` | intentionally public | Helper payload required by `SessionStore` session create and lookup methods. |
| `SessionStore` | intentionally public | Adapter-facing trait implemented outside the crate. |
| `TokenSigner` | intentionally public | Adapter-facing trait implemented outside the crate. |
| `UserCredentials` | intentionally public | Helper payload required by email and username credential lookup methods. |
| `UserRepository` | intentionally public | Adapter-facing trait implemented outside the crate. |
| `TenantPolicyPort` | intentionally public | Adapter-facing trait for loading typed tenant auth policy. |
### RBAC
| `Permission` | intentionally public | Core authorization value object used by roles and policy checks. |
| `Role` | intentionally public | Tenant-scoped RBAC model returned by repositories and flows. |
| `RoleAssignment` | likely intentionally public | Public domain relation type; current flow and port use is lighter than `Role`, but the type is coherent as part of the RBAC model. |
| `RoleRegistry` | likely intentionally public | Public tenant-scoped role container, though not used by current service orchestration or port signatures. |
### session
| `RefreshToken` | intentionally public | Opaque refresh credential used by services and the `SessionStore` port. |
| `Session` | intentionally public | Core session model used by services and the `SessionStore` port. |
## Module Exports
### `nythos_core::auth`
Module-root re-exports:
- `AccessToken`
- `Claims`
- `PasswordHash`
- `TokenPurpose`
- `LoginAuthMaterial`
- `LoginInput`
- `LoginService`
- `RefreshAuthMaterial`
- `RefreshInput`
- `RefreshService`
- `RegisterAuthMaterial`
- `RegisterInput`
- `RegisterResult`
- `RegisterService`
- `RevokeAllSessionsInput`
- `RevokeAllSessionsService`
- `RevokeResult`
- `RevokeSessionInput`
- `RevokeSessionService`
Public submodules:
- `login`
- `refresh`
- `register`
- `revoke`
- `tokens`
Assessment:
- The module-root re-export surface looks intentionally curated and useful.
- The deeper paths under `login`, `refresh`, `register`, and `revoke` look more like implementation file layout than a separately designed stable public namespace.
### `nythos_core::domain`
Module-root re-exports:
- typed IDs: `UserId`, `TenantId`, `SessionId`, `RoleId`
- value objects: `Email`, `Password`, `Username`, `DisplayName`, `LoginIdentifier`
- identity models: `User`, `UserStatus`, `Tenant`, `TenantSettings`, `TenantAuthPolicy`
Public submodules:
- `identity`
- `ids`
- `value_objects`
Assessment:
- The submodules map to meaningful domain categories rather than flow implementation details.
- These public submodules are easier to justify as stable than the deeper `auth` flow submodules.
### `nythos_core::ports`
Module-root re-exports:
- traits: `UserRepository`, `TenantPolicyPort`, `RoleRepository`, `SessionStore`, `PasswordHasher`, `TokenSigner`, `RevocationChecker`
- helper payloads: `NewUser`, `UserCredentials`, `RoleAssignmentInput`, `SessionRecord`, `RefreshTokenRotation`
Public submodules:
- `user`
- `role`
- `session`
- `security`
- `tenant_policy`
Assessment:
- The module-root surface is clearly adapter-facing and intentional.
- The public submodules are category-oriented and likely fine to keep public, even if callers usually prefer the `ports::*` re-exports.
### `nythos_core::rbac`
Exports:
- `Permission`
- `Role`
- `RoleAssignment`
- `RoleRegistry`
Assessment:
- Single direct module with no extra internal path layering.
- Public surface looks like a straightforward RBAC domain API.
### `nythos_core::session`
Exports:
- `Session`
- `RefreshToken`
Assessment:
- Single direct module with no extra internal path layering.
- Public surface looks intentionally domain-facing and port-facing.
### `nythos_core::error`
Exports:
- `AuthError`
- `NythosResult`
Assessment:
- Single direct module with no extra internal path layering.
- Public surface is minimal and clearly intentional.
## Intended Public Categories
### Domain API
Types users of the crate need to construct, validate, inspect, and pass around.
Current examples:
- `Email`
- `Username`
- `DisplayName`
- `LoginIdentifier`
- `Password`
- `UserId`
- `TenantId`
- `SessionId`
- `RoleId`
- `User`
- `UserStatus`
- `Tenant`
- `TenantSettings`
- `TenantAuthPolicy`
- `Permission`
- `Role`
- `RoleAssignment`
- `RoleRegistry`
- `Session`
- `RefreshToken`
- `AccessToken`
- `Claims`
- `PasswordHash`
### Adapter-facing API
Types and traits outer implementations need in order to implement storage, signing, hashing, revocation, and role or user or session lookup.
Current examples:
- `UserRepository`
- `TenantPolicyPort`
- `RoleRepository`
- `SessionStore`
- `PasswordHasher`
- `TokenSigner`
- `RevocationChecker`
- `NewUser`
- `UserCredentials`
- `RoleAssignmentInput`
- `SessionRecord`
- `RefreshTokenRotation`
### Flow or service API
Inputs, outputs, and services needed to run register, login, refresh, and revoke orchestration.
Current examples:
- `RegisterInput`
- `RegisterAuthMaterial`
- `RegisterResult`
- `RegisterService`
- `LoginInput`
- `LoginAuthMaterial`
- `LoginService`
- `RefreshInput`
- `RefreshAuthMaterial`
- `RefreshService`
- `RevokeSessionInput`
- `RevokeAllSessionsInput`
- `RevokeResult`
- `RevokeSessionService`
- `RevokeAllSessionsService`
### Possibly accidental or internal API
Public items that may be public today because the module structure exposes them, not because external users should depend on them long-term.
Current strongest candidates:
- deeper `auth` implementation-shaped module paths such as `nythos_core::auth::register::RegisterService`
- public constructors on service output wrappers such as `LoginAuthMaterial::new`, `RefreshAuthMaterial::new`, and `RegisterAuthMaterial::new`
- public constructors on result wrappers such as `RegisterResult::new` and `RevokeResult::new`
- lower-pressure exports that may deserve a later scope decision, such as `TokenPurpose` and `TenantSettings`
## Adapter-facing Types That Look Intentionally Public
These items are strongly justified by the current implemented port boundaries and should be treated as intentionally public.
| `UserRepository` | Outer storage layer implements tenant-scoped user lookup and creation. |
| `TenantPolicyPort` | Outer policy layer loads typed tenant auth policy for service-side decisions. |
| `RoleRepository` | Outer storage layer implements tenant-scoped role lookup and mutation. |
| `SessionStore` | Outer storage layer implements session creation, refresh-token lookup, rotation, and revocation. |
| `PasswordHasher` | Outer security layer hashes and verifies `Password` values into `PasswordHash`. |
| `TokenSigner` | Outer security layer signs and verifies `Claims` into `AccessToken`. |
| `RevocationChecker` | Outer request-time or refresh-time enforcement checks session revocation status. |
| `NewUser` | Required input to `UserRepository::create`; now carries optional username and display name. |
| `UserCredentials` | Required output from email and username credential lookup methods. |
| `RoleAssignmentInput` | Required input to `RoleRepository::assign_role` and `RoleRepository::revoke_role`. |
| `SessionRecord` | Required input and output shape around `SessionStore` create and refresh-token lookup. |
| `RefreshTokenRotation` | Required input to `SessionStore::rotate_refresh_token`. |
| `User` | Repository output and flow output. |
| `UserId` | Used by repositories, sessions, RBAC, and flows. |
| `TenantId` | Used across repository and service boundaries. |
| `SessionId` | Used by session and revocation boundaries. |
| `RoleId` | Used by RBAC boundaries. |
| `Email` | Used by repository boundaries and user identity. |
| `Username` | Used by repository boundaries and optional user identity. |
| `DisplayName` | Used by optional user profile identity. |
| `LoginIdentifier` | Used by login service branching before repository lookup. |
| `TenantAuthPolicy` | Used by `Tenant` and `TenantPolicyPort` for typed auth policy. |
| `Password` | Used by `PasswordHasher`. |
| `PasswordHash` | Used by `PasswordHasher`, `UserRepository`, and `UserCredentials`. |
| `AccessToken` | Used by `TokenSigner` and flow outputs. |
| `Claims` | Used by `TokenSigner` and auth material outputs. |
| `RefreshToken` | Used by `SessionStore`, refresh flows, and auth material outputs. |
| `Session` | Used by `SessionStore` and auth material outputs. |
| `Role` | Used by `RoleRepository` and auth material outputs. |
## Possibly Accidental Exports And Recommendations
### 1. Public `auth` implementation submodules
Current public submodules:
- `nythos_core::auth::login`
- `nythos_core::auth::refresh`
- `nythos_core::auth::register`
- `nythos_core::auth::revoke`
- `nythos_core::auth::tokens`
Recommendation:
- Keep as-is for `v0.2.0`.
- Treat `nythos_core::auth::*` module-root re-exports as the primary supported `auth` surface.
- In a later explicit cleanup window, consider making the flow-oriented submodules private while preserving the `auth` module-root re-exports.
### 2. Public constructors on output-only wrappers
Current examples:
- `LoginAuthMaterial::new`
- `RefreshAuthMaterial::new`
- `RegisterAuthMaterial::new`
- `RegisterResult::new`
- `RevokeResult::new`
Recommendation:
- Keep as-is for `v0.2.0`.
- In a later explicit cleanup window, consider narrowing constructors for output-only types if callers are expected to receive these mostly from services rather than construct them directly.
### 3. `Claims::new` plus `TokenPurpose`
Current situation:
- `Claims::access` already covers the common auth-flow issuance path.
- `TokenSigner::verify` returns `Claims`, so external callers and adapter implementations still need to inspect the claim shape.
- `TokenPurpose` currently has only one variant, `Access`.
Recommendation:
- Keep both public for `v0.2.0`.
- Later decide whether `Claims::new` should remain a general public constructor or whether `Claims::access` is the intended stable constructor for most callers.
- Later document whether `TokenPurpose` is expected to grow or should stay minimal.
### 4. `TenantSettings`
Current situation:
- `TenantSettings` is public because `Tenant::with_settings` and `Tenant::settings` expose it directly.
- It is not used for auth policy decisions.
- Current auth flow services use typed `TenantAuthPolicy` loaded through `TenantPolicyPort`.
Recommendation:
- Keep as-is for `v0.2.0`.
- Revisit only if the crate later narrows tenant metadata scope or moves plain tenant settings out of the core domain model.
## v0.2.0 API Notes
New public domain API:
- `Username`
- `DisplayName`
- `LoginIdentifier`
- `TenantAuthPolicy`
Updated public domain API:
- `User` now carries optional `Username` and `DisplayName`
- `Tenant` now embeds `TenantAuthPolicy` alongside slug and optional `TenantSettings`
Updated adapter-facing API:
- `TenantPolicyPort` was added
- `NewUser` now supports optional profile fields
- `UserRepository` now includes `find_by_username` and `find_credentials_by_username`
Updated flow or service API:
- `RegisterInput` accepts optional raw username and display-name fields
- `RegisterService::new` now requires a `TenantPolicyPort` dependency
- `LoginInput` now stores a raw identifier string internally
- `LoginInput::new_with_identifier` was added
- `LoginService::new` now requires a `TenantPolicyPort` dependency
Compatibility notes:
- `User::new` is preserved
- `User::with_status` is preserved
- `NewUser::new` is preserved
- `RegisterInput::new` is preserved
- `LoginInput::new(..., email: String, ...)` is preserved as a compatibility constructor
- `LoginInput::email()` is preserved as a compatibility alias returning the raw identifier string
- `UserRepository` is source-breaking for implementors because it adds username lookup methods
- `RegisterService::new` and `LoginService::new` are source-breaking for callers because they now require `TenantPolicyPort`
Explicit non-API in `v0.2.0`:
- no `find_credentials_by_identifier` repository method
- no OAuth provider or OAuth flow API
- no HTTP handlers, database adapters, migrations, gateway code, worker code, or concrete crypto library bindings
### 5. Stable path ambiguity
Current situation:
- Many items are reachable through three layers today: crate root, module root, and deeper public submodule path.
- Example: `RegisterService` is currently reachable as `nythos_core::RegisterService`, `nythos_core::auth::RegisterService`, and `nythos_core::auth::register::RegisterService`.
Recommendation:
- For future docs, treat crate-root re-exports as the main ergonomic API.
- Treat `auth`, `domain`, and `ports` module-root re-exports as supported grouped access paths.
- Avoid promising that deeper implementation-shaped submodule paths are stable until an explicit API cleanup and documentation pass says so.
## Recommendations for future API cleanup
- Keep the current crate-root re-exports as the main ergonomic API for `v0.2.0`.
- Keep `nythos_core::auth::*`, `nythos_core::domain::*`, and `nythos_core::ports::*` module-root re-exports as the grouped public surface.
- Consider making `auth` implementation submodules private later while preserving module-root re-exports.
- Consider documenting stable paths explicitly: crate root and module-root re-exports first, deeper implementation submodule paths unspecified unless later committed.
- Consider narrowing public constructors for output-only wrappers and result wrappers in a later explicit cleanup window.
- Keep `TokenPurpose` public for `v0.2.0`, then revisit only if token-purpose expansion or claim-construction rules become a real API pressure point.
- Keep `TenantSettings` public for `v0.2.0`, then revisit only if tenant metadata scope is intentionally reduced.
- Do not add `#[doc(hidden)]` in this issue; only consider it in a later explicit compatibility cleanup if a public item must remain exported but should be deemphasized.
- Do not add a prelude for `v0.2.0`; only consider one later if real usage pressure shows repeated import friction.
## Conclusion
The current public surface is aligned with the implemented `v0.2.0` identity profile and login identifier work.
The public crate-root items mostly look intentional and aligned with the implemented domain, adapter, and orchestration boundaries. The main future cleanup work is not removing major types, but tightening path stability and deciding whether a few constructors and implementation-shaped submodule paths should remain part of the long-term supported API.