@bentoforge/umami-iam 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -5,9 +5,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;
@@ -49,9 +47,25 @@ 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;
+}
+/** 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 type UserStatus = "Active" | "Locked" | "Invited";
-export interface UserView {
+export interface UserView extends NameParts {
     userId: string;
     tenantId: string;
     roles: string[];
@@ -59,111 +73,133 @@ 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>;
 }
+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;
 }
-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;
 }
 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>;
 }
 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;
 }
 /** A role assignable to a user (`role:*`). Permissions come from the per-API rules, not here. */
 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;
 }
@@ -171,38 +207,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;
@@ -211,6 +230,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`). */
 export interface CustomFieldsSchema {
@@ -239,7 +260,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>;
 }
 export interface Config {
@@ -248,10 +271,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;
@@ -271,8 +294,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;
@@ -284,8 +307,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;
 }
@@ -294,8 +317,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;
 }
 export interface CreateApiKeyResponse {
@@ -315,6 +336,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). */
 export interface MessagingConfig {
@@ -343,13 +367,16 @@ export interface MessagingLink {
 export interface ResolvedMessagingUser {
     userId: string;
     tenantId: string;
-    name: string;
     email?: string | null;
-    locale: string;
     roles: string[];
 }
 /** 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. */
@@ -358,6 +385,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. */
 export interface ResetPasswordResponse {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bentoforge/umami-iam",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Typed client SDK for the umami micro-IAM service",
   "type": "module",
   "main": "./dist/index.js",