@bentoforge/umami-iam 0.1.1 → 0.2.0

package/src/types.ts

@@ -9,9 +9,7 @@ export interface AccessClaims {
   aud?: string;
   /** The active tenant this token is scoped to. */
   tenant: string;
-  name: string;
   email: string;
-  locale: string;
   permissions: string[];
   iat: number;
   exp: number;
@@ -61,13 +59,30 @@ export interface TotpSetup {
   secret: string;
   /** `otpauth://` URL for QR rendering. */
   otpauthUrl: string;
+  /** Ready-to-render QR-code SVG of `otpauthUrl` (dark on white). */
+  qrSvg: string;
 }
 
 // ── Users ───────────────────────────────────────────────────────────────────
 
-export type UserStatus = "Active" | "Locked" | "Invited";
+/** How to address a user; the rendered word is composed server-side from the config labels. */
+export type Salutation = "" | "SIR" | "MADAM";
+
+/** Structured name parts (editable) plus the server-composed display names (read-only). */
+export interface NameParts {
+  title: string | null;
+  salutation: Salutation;
+  firstname: string | null;
+  lastname: string | null;
+  /** `title firstname lastname`. */
+  name: string;
+  /** `salutation title firstname lastname`. */
+  fullName: string;
+  /** `salutation title lastname`. */
+  addressableName: string;
+}
 
-export interface UserView {
+export interface UserView extends NameParts {
   userId: string;
   tenantId: string;
   roles: string[];
@@ -75,95 +90,131 @@ export interface UserView {
   username: string;
   /** Optional contact email — not unique, may be null/absent. */
   email: string | null;
-  name: string;
-  locale: string;
-  status: UserStatus;
+  /** Admin lock — a locked user cannot log in. */
+  locked: boolean;
   customFields: Record<string, unknown>;
   /** RFC3339 creation timestamp. */
   created: string;
-  /** RFC3339 timestamp of the user's last authentication (login/refresh). */
-  lastSeen: string;
-}
-
-export interface CreateUserRequest {
+  /** RFC3339 timestamp of the last change to this record. */
+  lastUpdated: string;
+  /** RFC3339 timestamp of the user's last authentication (login/refresh); null until first active. */
+  lastSeen: string | null;
+  /** User id that created / last changed this user (audit; not surfaced in the UI yet). */
+  createdBy?: string | null;
+  lastChangedBy?: string | null;
+  /** Whether TOTP MFA is configured (never exposes the secret). */
+  mfaEnabled: boolean;
+  /** Whether the current password came from an admin reset and hasn't been changed since. */
+  passwordGenerated: boolean;
+  /** Whether the user has at least one registered passkey. */
+  hasPasskey: boolean;
+}
+
+/** The editable structured name parts (all optional; omitted = unset, `""` clears). */
+export interface NameInput {
+  title?: string;
+  salutation?: Salutation;
+  firstname?: string;
+  lastname?: string;
+}
+
+export interface CreateUserRequest extends NameInput {
   /** Login username (unique). If omitted, `email` is used as the username. */
   username?: string;
   /** Optional contact email (not unique). */
   email?: string;
-  password: string;
-  name: string;
-  locale?: string;
+  /** Optional initial password. Omit (the normal case) to have a temporary one generated and
+   * returned once in {@link CreateUserResponse.temporaryPassword}. */
+  password?: string;
   roles?: string[];
   customFields?: Record<string, unknown>;
 }
 
-export interface PatchUserRequest {
+/** The created user, plus the one-time temporary password when one was generated. */
+export type CreateUserResponse = UserView & {
+  /** Present only when the server generated the initial password — shown once. */
+  temporaryPassword?: string | null;
+};
+
+export interface PatchUserRequest extends NameInput {
+  /** New login username (globally unique). Omit to leave unchanged; must not be empty. */
+  username?: string;
+  /** Contact email. Omit to leave unchanged; empty string clears it. */
+  email?: string;
   roles?: string[];
-  status?: UserStatus;
+  locked?: boolean;
   customFields?: Record<string, unknown>;
 }
 
 // ── Me ──────────────────────────────────────────────────────────────────────
 
+export interface MeUser extends NameParts {
+  userId: string;
+  tenantId: string;
+  roles: string[];
+  username: string;
+  email: string | null;
+  locked: boolean;
+  customFields: Record<string, unknown>;
+  /** Whether TOTP MFA is configured (never exposes the secret). */
+  mfaEnabled: boolean;
+  /** Whether the caller has at least one registered passkey. */
+  hasPasskey: boolean;
+}
+
 export interface MeResponse {
-  user: {
-    userId: string;
-    tenantId: string;
-    roles: string[];
-    username: string;
-    email: string | null;
-    name: string;
-    locale: string;
-    status: UserStatus;
-  };
+  user: MeUser;
   tenant: Tenant | null;
 }
 
-// ── Tenants ──────────────────────────────────────────────────────────────────
-
-export type TenantStatus = "Lead" | "Testing" | "Onboarding" | "Active" | "Suspended" | "Churned";
-
-export type FeatureToggle = "standard" | "on" | "off";
-
-export interface PackageAssignment {
-  id: string;
-  code: string;
-  assignedAt: string;
-  accountedUntil?: string | null;
-  monthlyPrice?: string | null;
-  priceFixedUntil?: string | null;
-  active: boolean;
+/** One of the caller's active login sessions (device). Never exposes the refresh secret. */
+export interface SessionView {
+  sessionId: string;
+  userAgent?: string;
+  ip?: string;
+  /** RFC3339 creation timestamp. */
+  created: string;
+  /** RFC3339 timestamp of the last refresh. */
+  lastSeen: string;
+  /** RFC3339 absolute expiry. */
+  expiresAt: string;
+  /** Whether this is the session making the request. */
+  current: boolean;
 }
 
+// ── Tenants ──────────────────────────────────────────────────────────────────
+
 export interface Tenant {
   tenantId: string;
   version: number;
-  packages: PackageAssignment[];
-  limitOverrides: Record<string, string>;
-  featureOverrides: Record<string, FeatureToggle>;
   /** Authorization features granted to the tenant (`feature:*`), fed to the token broker. */
   features: string[];
   customFields: Record<string, unknown>;
   name: string;
   slug: string;
-  status: TenantStatus;
-  plan: string;
-  billedUntil?: string | null;
-  seatsLimit?: number | null;
   created: string;
   lastUpdated: string;
+  /** RFC3339 timestamp of the last token activity (refresh / exchange) scoped to this tenant;
+   * null until the first activity. */
+  lastActive?: string | null;
+  /** Sort key backing the tenant listing: `lastActive` when present, else `created`. */
+  lastActiveOrCreated?: string;
+  /** User id that created this tenant (audit; not surfaced in the UI yet). */
+  createdBy?: string | null;
+  /** User id of the last change to this tenant (audit; not surfaced in the UI yet). */
+  lastChangedBy?: string | null;
 }
 
 export interface CreateTenantRequest {
   name: string;
-  owner: {
+  /** Optional first owner. Omit to create an empty tenant (add users afterwards by impersonating
+   * it on the Tenants screen). */
+  owner?: {
     /** Owner login username (unique). If omitted, `email` is used as the username. */
     username?: string;
     /** Optional contact email (not unique). */
     email?: string;
     password: string;
-    name: string;
-    locale?: string;
   };
   /** Custom-field values, validated against `customTenantFields`. */
   customFields?: Record<string, unknown>;
@@ -171,26 +222,8 @@ export interface CreateTenantRequest {
 
 export interface CreateTenantResponse {
   tenantId: string;
-  ownerUserId: string;
-}
-
-export interface EntitlementsResponse {
-  limits: Record<string, string>;
-  features: string[];
-  monthlyTotal: string;
-  packages: PackageAssignment[];
-}
-
-export interface MetricUsage {
-  metric: string;
-  used: number;
-  limit?: string;
-  overQuota: boolean;
-}
-
-export interface UsageResponse {
-  period: string;
-  metrics: MetricUsage[];
+  /** The created owner's user id — only present when an `owner` was supplied. */
+  ownerUserId: string | null;
 }
 
 // ── Config ────────────────────────────────────────────────────────────────────
@@ -199,6 +232,8 @@ export interface UsageResponse {
 export interface RoleDef {
   code: string;
   name: string;
+  /** Optional human-readable description (shown muted under the name in the admin UI). */
+  description?: string | null;
   /** Boolean expression over the tenant's `feature:*`/`is:*` gating whether it may be assigned. */
   assignableIf?: string | null;
 }
@@ -206,38 +241,21 @@ export interface RoleDef {
 export interface ScopeDef {
   code: string;
   name: string;
+  /** Optional human-readable description (shown muted under the name in the admin UI). */
+  description?: string | null;
   assignableIf?: string | null;
 }
 /** An authorization feature granted to a tenant (`feature:*`). */
 export interface FeatureDef {
   code: string;
   name: string;
+  /** Optional human-readable description (shown muted under the name in the admin UI). */
+  description?: string | null;
   /** Boolean expression over the tenant's current features gating whether it may be granted. */
   assignableIf?: string | null;
 }
-export interface LimitDef {
-  code: string;
-  name: string;
-  unit?: string;
-  default?: string;
-}
-export interface PackageLimit {
-  code: string;
-  value: string;
-}
-export interface PriceEntry {
-  validFrom: string;
-  price: string;
-}
-export interface PackageDef {
-  code: string;
-  name: string;
-  features: string[];
-  limits: PackageLimit[];
-  prices: PriceEntry[];
-}
 export interface CustomFieldDef {
-  key: string;
+  code: string;
   label: string;
   /** `"string"` | `"number"` | `"bool"` | `"select"`. */
   type: string;
@@ -246,6 +264,8 @@ export interface CustomFieldDef {
   required: boolean;
   /** Whether admin list tables surface this field as a column. */
   showInTable?: boolean;
+  /** Whether the user may edit this field on themselves via `PATCH /auth/me`. */
+  selfEditable?: boolean;
 }
 
 /** The custom-field schemas for rendering user/tenant forms (`GET /config/custom-fields`). */
@@ -275,7 +295,9 @@ export interface ApiDef {
   eligibility?: string | null;
   /** Ordered rules mapping subjects → granted permissions (accumulated top-to-bottom). */
   permissions: PermissionRule[];
-  /** Claim mapping: claimName → source (`customUser:<k>`, `customTenant:<k>`, or a literal). */
+  /** Claim mapping: claimName → source. A source is a literal string, a `$user.<field>` /
+   * `$tenant.<field>` reference (`id`, `username`, `email`, `name`, `fullName`, `addressableName`,
+   * `roles`, `name`/`slug`/`features`, …), or `$user.custom.<key>` / `$tenant.custom.<key>`. */
   claims?: Record<string, string>;
 }
 
@@ -285,10 +307,10 @@ export interface Config {
   /** Scopes assignable to M2M service keys. */
   scopes: ScopeDef[];
   features: FeatureDef[];
-  limits: LimitDef[];
-  packages: PackageDef[];
   customTenantFields: CustomFieldDef[];
   customUserFields: CustomFieldDef[];
+  /** Salutation labels (`salutationCode → word`) in the deployment's language. */
+  salutations: Record<string, string>;
   security: SecuritySettings;
   /** Messaging integration (Telegram/WhatsApp) settings. */
   messaging?: MessagingConfig;
@@ -312,8 +334,8 @@ export interface ApiKeyView {
   roles: string[];
   /** Service-key `scope:*` subjects (empty for PATs). */
   scopes: string[];
-  /** Target API codes this key may mint tokens for. */
-  apis: string[];
+  /** Whether the raw-secret (Mode 1) exchange is allowed; false ⇒ HMAC-only (Mode 2). */
+  allowSecretLogin: boolean;
   status: ApiKeyStatus;
   allowedOrigins: string[];
   expiresAt?: string | null;
@@ -326,8 +348,8 @@ export interface CreateApiKeyRequest {
   name: string;
   /** The `scope:*` subjects this key carries (must be assignable given the tenant's features). */
   scopes?: string[];
-  /** Target API codes this key may mint for; defaults to `["umami"]`. */
-  apis?: string[];
+  /** Allow the raw-secret (Mode 1) exchange; omitted/false ⇒ HMAC-only (Mode 2). */
+  allowSecretLogin?: boolean;
   allowedOrigins?: string[];
   expiresAt?: string;
 }
@@ -337,8 +359,6 @@ export interface CreatePatRequest {
   name: string;
   /** Restrict the token to this subset of your own `role:*` (empty = all your roles). */
   roles?: string[];
-  /** Target API codes this PAT may mint for; defaults to `["umami"]`. */
-  apis?: string[];
   expiresAt?: string;
 }
 
@@ -360,6 +380,9 @@ export interface BrandingConfig {
   /** Logo for dark backgrounds; falls back to logoLight, then default. */
   logoDark?: string;
   favicon?: string;
+  /** Browser tab title (document `<title>`); served at /app/branding.json, applied at runtime.
+   * Empty → "umami". */
+  title?: string;
 }
 
 /** Messaging integration settings (Telegram/WhatsApp). */
@@ -394,9 +417,7 @@ export interface MessagingLink {
 export interface ResolvedMessagingUser {
   userId: string;
   tenantId: string;
-  name: string;
   email?: string | null;
-  locale: string;
   roles: string[];
 }
 
@@ -405,6 +426,12 @@ export interface ResolvedMessagingUser {
 /** Outcome flavour of an audited event. */
 export type AuditSeverity = "good" | "neutral" | "bad";
 
+/** One page of audit entries plus the cursor to fetch the next (absent when the trail is exhausted). */
+export interface AuditPage {
+  entries: AuditEntry[];
+  nextCursor?: string;
+}
+
 export interface AuditEntry {
   id: string;
   /** RFC3339 event time. */
@@ -413,6 +440,9 @@ export interface AuditEntry {
   user?: string | null;
   severity: AuditSeverity;
   message: string;
+  /** Best-effort client IP, present on security-relevant events (logins, credential/account
+   * changes). Absent on events with no request IP. */
+  ip?: string | null;
 }
 
 /** Result of an admin password reset — `temporaryPassword` is set (once) only when generated. */