@bentoforge/umami-iam 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The umami authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AccessClaims, ApiErrorBody, ApiKeyView, AuditEntry, Config, CreateApiKeyRequest, CreateApiKeyResponse, CreatePatRequest, CreateTenantRequest, CreateTenantResponse, CreateUserRequest, CustomFieldsSchema, EntitlementsResponse, ExchangeResponse, FeatureToggle, LoginResponse, MeResponse, MessagingCodeResponse, MessagingLink, MetricUsage, MfaStatus, PatchUserRequest, ResetPasswordResponse, ResolvedMessagingUser, Tenant, TenantStatus, TotpSetup, UsageResponse, UserView } from "./types.js";
+import type { AccessClaims, ApiErrorBody, ApiKeyView, AuditPage, Config, CreateApiKeyRequest, CreateApiKeyResponse, CreatePatRequest, CreateTenantRequest, CreateTenantResponse, CreateUserRequest, CreateUserResponse, CustomFieldsSchema, ExchangeResponse, LoginResponse, MeResponse, MessagingCodeResponse, MessagingLink, MfaStatus, NameInput, PatchUserRequest, ResetPasswordResponse, ResolvedMessagingUser, SessionView, Tenant, TotpSetup, UserView } from "./types.js";
 /** An error carrying the server's HTTP status and (parsed) body. */
 export declare class UmamiError extends Error {
     readonly status: number;
@@ -19,6 +19,8 @@ export declare class UmamiClient {
     private readonly baseUrl;
     private readonly onTokenChange?;
     private accessToken;
+    /** In-flight refresh, if any — coalesces concurrent 401s into a single rotation. */
+    private refreshing;
     constructor(options: UmamiClientOptions);
     /** The current in-memory access token, if any. */
     getAccessToken(): string | null;
@@ -33,23 +35,32 @@ export declare class UmamiClient {
     private handle;
     /** Password login by username. On success the access token is stored; if MFA is enabled and no
      * `totpCode` is given, the response has `mfaRequired: true` and no token. Pass `api` to mint the
-     * token for a product API directly (default: the umami admin API); the session keeps that
-     * audience across refreshes. */
+     * first token for a product API directly (default: the umami admin API); the session itself is
+     * audience-agnostic, so later `refresh` calls choose their own `api`. */
     login(username: string, password: string, totpCode?: string, api?: string): Promise<LoginResponse>;
-    /** Silent refresh via the cookie. Returns whether a fresh token was obtained. */
+    /** Silent refresh via the cookie. Returns whether a fresh token was obtained.
+     *
+     * Single-flighted: concurrent callers (e.g. several requests that 401 at once) all await one
+     * rotation. Without this, the second refresh would send the just-rotated-out cookie secret, which
+     * the server treats as token reuse and revokes the whole session. */
     refresh(): Promise<boolean>;
+    private doRefresh;
     /** Logs out this device and clears the in-memory token. */
     logout(): Promise<void>;
     /** Revokes all of the user's sessions (bumps `tokenVersion`). */
     logoutAll(): Promise<void>;
+    /** Lists the caller's active login sessions (the current one is flagged). */
+    listSessions(): Promise<SessionView[]>;
+    /** Revokes one of the caller's own sessions (single-device logout). */
+    deleteSession(sessionId: string): Promise<void>;
     /** Current profile (user + tenant). */
     getMe(): Promise<MeResponse>;
-    /** Update the caller's own profile (name/locale). Blocked for `self:readonly` users. */
-    patchMe(body: {
-        name?: string;
-        locale?: string;
+    /** Self-service profile edit: the structured name parts are always editable; custom fields only
+     * when marked `selfEditable`. Blocked for `self:readonly` users. */
+    patchMe(body: NameInput & {
+        customFields?: Record<string, unknown>;
     }): Promise<MeResponse>;
-    /** Re-scope the access token to another tenant (requires `admin:system`). Access-token only —
+    /** Re-scope the access token to another tenant (requires `switch:tenant`). Access-token only —
      * a later silent refresh returns to the home tenant. Returns the active tenant id. */
     switchTenant(tenantId: string): Promise<string>;
     totpSetup(): Promise<TotpSetup>;
@@ -66,14 +77,14 @@ export declare class UmamiClient {
     /** Exchanges an `umk_…` API key for a short-lived token (stores it). Server-side/BFF use.
      * `api` selects the target API when the key allows more than one (see `docs/AUDIENCES.md`). */
     exchangeApiKey(apiKey: string, api?: string): Promise<ExchangeResponse>;
-    /** Downstream token exchange: mints a token for a product API (`api` from the config catalog)
-     * for the currently-logged-in user, WITHOUT replacing the stored umami token. Returns the
-     * downstream token for the caller to use against that API. */
-    exchange(api: string): Promise<ExchangeResponse>;
+    /** Mode 2 exchange: prove possession of `keyId`/`secret` with an HMAC over the current hour bucket
+     * instead of sending the secret. Same result as {@link exchangeApiKey}; the raw secret never
+     * leaves the process. `secret` is the part after `umk_<keyId>_`. Uses WebCrypto (Node 18+/browser). */
+    exchangeApiKeyHmac(keyId: string, secret: string, api?: string): Promise<ExchangeResponse>;
     /** List every tenant (system-admin only; sorted newest-updated first, capped at 250). `q` is an
      * optional case-insensitive search: whitespace-separated terms must all match (over name / slug /
      * custom fields). `truncated` is true when more than 250 matched. */
-    listTenants(q?: string): Promise<{
+    listTenants(q?: string, limit?: number): Promise<{
         tenants: Tenant[];
         truncated: boolean;
     }>;
@@ -84,20 +95,7 @@ export declare class UmamiClient {
         status: string;
     }>;
     getTenant(tenantId: string): Promise<Tenant>;
-    patchTenant(tenantId: string, body: Partial<Pick<Tenant, "name" | "plan" | "customFields">>): Promise<Tenant>;
-    patchStatus(tenantId: string, status: TenantStatus): Promise<Tenant>;
-    patchLicense(tenantId: string, body: {
-        plan?: string;
-        billedUntil?: string;
-        seatsLimit?: number;
-    }): Promise<Tenant>;
-    getEntitlements(tenantId: string): Promise<EntitlementsResponse>;
-    assignPackage(tenantId: string, request: {
-        code: string;
-        monthlyPrice?: string;
-    }): Promise<Tenant>;
-    removePackage(tenantId: string, assignmentId: string): Promise<Tenant>;
-    setFeature(tenantId: string, code: string, value: FeatureToggle): Promise<Tenant>;
+    patchTenant(tenantId: string, body: Partial<Pick<Tenant, "name" | "customFields">>): Promise<Tenant>;
     /** Role codes assignable to a user given their tenant's features (feeds the UI role picker). */
     assignableRoles(userId: string): Promise<{
         codes: string[];
@@ -118,15 +116,15 @@ export declare class UmamiClient {
     revokeFeature(tenantId: string, code: string): Promise<{
         status: string;
     }>;
-    getUsage(tenantId: string): Promise<UsageResponse>;
-    incrementUsage(tenantId: string, metric: string, amount?: number): Promise<MetricUsage>;
-    createUser(request: CreateUserRequest): Promise<UserView>;
+    createUser(request: CreateUserRequest): Promise<CreateUserResponse>;
     /** List the caller's tenant's users (sorted by recent activity, capped at 250). `q` is an
      * optional case-insensitive search over username / email / name / custom fields. */
-    listUsers(q?: string): Promise<{
+    listUsers(q?: string, limit?: number): Promise<{
         users: UserView[];
         truncated: boolean;
     }>;
+    /** Read one user in the caller's tenant (requires `manage:users`). */
+    getUser(userId: string): Promise<UserView>;
     patchUser(userId: string, body: PatchUserRequest): Promise<UserView>;
     /** Hard-delete a user in the caller's tenant (cannot delete your own account). */
     deleteUser(userId: string): Promise<{
@@ -137,10 +135,16 @@ export declare class UmamiClient {
     resetPassword(userId: string, newPassword?: string): Promise<ResetPasswordResponse>;
     /** Change the current user's own password (verifies the current one; logs out other sessions). */
     changePassword(currentPassword: string, newPassword: string): Promise<void>;
-    /** The current user's own audit trail (newest first). */
-    myAudit(limit?: number): Promise<AuditEntry[]>;
-    /** A tenant's audit trail (requires `admin:tenant`; own tenant). */
-    tenantAudit(tenantId: string, limit?: number): Promise<AuditEntry[]>;
+    /** One page of the current user's own audit trail (newest first). Pass `cursor` to page. */
+    myAudit(limit?: number, cursor?: string): Promise<AuditPage>;
+    /** One page of a tenant's audit trail (requires `admin:tenant`; own tenant). */
+    tenantAudit(tenantId: string, limit?: number, cursor?: string): Promise<AuditPage>;
+    /** One page of a tenant user's audit trail (requires `manage:users`; own tenant). */
+    userAudit(userId: string, limit?: number, cursor?: string): Promise<AuditPage>;
+    /** A tenant user's active login sessions (requires `manage:users`; own tenant). */
+    userSessions(userId: string): Promise<SessionView[]>;
+    /** Revokes all of a tenant user's sessions by bumping their tokenVersion (requires `manage:users`). */
+    logoutUser(userId: string): Promise<void>;
     /** The caller's current link code (rotated if expired), with deep links when configured. */
     getMessagingCode(): Promise<MessagingCodeResponse>;
     /** Replace the caller's link code (invalidates the old). */
@@ -153,6 +157,8 @@ export declare class UmamiClient {
     deleteMessagingLink(platform: string, externalId: string): Promise<{
         status: string;
     }>;
+    /** A tenant user's linked identities, read-only (requires `manage:users`; own tenant). */
+    listUserMessagingLinks(userId: string): Promise<MessagingLink[]>;
     /** Machine (`messaging:link`): claim a `(platform, externalId)` mapping from a link code. */
     createMessagingLink(code: string, platform: string, externalId: string): Promise<{
         userId: string;
@@ -177,4 +183,6 @@ export declare class UmamiClient {
     createMyPat(request: CreatePatRequest): Promise<CreateApiKeyResponse>;
     listMyPats(): Promise<ApiKeyView[]>;
     deleteMyPat(keyId: string): Promise<void>;
+    /** A tenant user's personal access tokens, read-only (requires `manage:users`; own tenant). */
+    listUserPats(userId: string): Promise<ApiKeyView[]>;
 }

package/dist/client.js

@@ -15,6 +15,8 @@ export class UmamiError extends Error {
 export class UmamiClient {
     constructor(options) {
         this.accessToken = null;
+        /** In-flight refresh, if any — coalesces concurrent 401s into a single rotation. */
+        this.refreshing = null;
         this.baseUrl = options.baseUrl.replace(/\/+$/, "");
         this.onTokenChange = options.onTokenChange;
     }
@@ -85,16 +87,28 @@ export class UmamiClient {
     // ── auth ────────────────────────────────────────────────────────────────────
     /** Password login by username. On success the access token is stored; if MFA is enabled and no
      * `totpCode` is given, the response has `mfaRequired: true` and no token. Pass `api` to mint the
-     * token for a product API directly (default: the umami admin API); the session keeps that
-     * audience across refreshes. */
+     * first token for a product API directly (default: the umami admin API); the session itself is
+     * audience-agnostic, so later `refresh` calls choose their own `api`. */
     async login(username, password, totpCode, api) {
         const data = await this.request("/auth/login", { method: "POST", body: JSON.stringify({ username, password, totpCode, api }) }, false);
         if (data.accessToken)
             this.setToken(data.accessToken);
         return data;
     }
-    /** Silent refresh via the cookie. Returns whether a fresh token was obtained. */
+    /** Silent refresh via the cookie. Returns whether a fresh token was obtained.
+     *
+     * Single-flighted: concurrent callers (e.g. several requests that 401 at once) all await one
+     * rotation. Without this, the second refresh would send the just-rotated-out cookie secret, which
+     * the server treats as token reuse and revokes the whole session. */
     async refresh() {
+        if (this.refreshing)
+            return this.refreshing;
+        this.refreshing = this.doRefresh().finally(() => {
+            this.refreshing = null;
+        });
+        return this.refreshing;
+    }
+    async doRefresh() {
         const response = await this.doFetch("/auth/refresh", { method: "POST" }, false);
         if (!response.ok) {
             this.setToken(null);
@@ -113,15 +127,27 @@ export class UmamiClient {
     async logoutAll() {
         await this.request("/auth/logout-all", { method: "POST" }, true);
     }
+    /** Lists the caller's active login sessions (the current one is flagged). */
+    listSessions() {
+        return this.request("/auth/sessions");
+    }
+    /** Revokes one of the caller's own sessions (single-device logout). */
+    async deleteSession(sessionId) {
+        await this.request(`/auth/sessions/${enc(sessionId)}`, { method: "DELETE" });
+    }
     /** Current profile (user + tenant). */
     getMe() {
         return this.request("/auth/me");
     }
-    /** Update the caller's own profile (name/locale). Blocked for `self:readonly` users. */
+    /** Self-service profile edit: the structured name parts are always editable; custom fields only
+     * when marked `selfEditable`. Blocked for `self:readonly` users. */
     patchMe(body) {
-        return this.request("/auth/me", { method: "PATCH", body: JSON.stringify(body) });
+        return this.request("/auth/me", {
+            method: "PATCH",
+            body: JSON.stringify(body),
+        });
     }
-    /** Re-scope the access token to another tenant (requires `admin:system`). Access-token only —
+    /** Re-scope the access token to another tenant (requires `switch:tenant`). Access-token only —
      * a later silent refresh returns to the home tenant. Returns the active tenant id. */
     async switchTenant(tenantId) {
         const data = await this.request("/auth/switch-tenant", {
@@ -194,22 +220,21 @@ export class UmamiClient {
         this.setToken(data.accessToken);
         return data;
     }
-    /** Downstream token exchange: mints a token for a product API (`api` from the config catalog)
-     * for the currently-logged-in user, WITHOUT replacing the stored umami token. Returns the
-     * downstream token for the caller to use against that API. */
-    exchange(api) {
-        return this.request("/auth/exchange", {
-            method: "POST",
-            body: JSON.stringify({ api }),
-        });
+    /** Mode 2 exchange: prove possession of `keyId`/`secret` with an HMAC over the current hour bucket
+     * instead of sending the secret. Same result as {@link exchangeApiKey}; the raw secret never
+     * leaves the process. `secret` is the part after `umk_<keyId>_`. Uses WebCrypto (Node 18+/browser). */
+    async exchangeApiKeyHmac(keyId, secret, api) {
+        const mac = await apiKeyMac(keyId, secret);
+        const data = await this.request("/auth/token", { method: "POST", body: JSON.stringify(api ? { keyId, mac, api } : { keyId, mac }) }, false);
+        this.setToken(data.accessToken);
+        return data;
     }
     // ── tenants ────────────────────────────────────────────────────────────────────
     /** List every tenant (system-admin only; sorted newest-updated first, capped at 250). `q` is an
      * optional case-insensitive search: whitespace-separated terms must all match (over name / slug /
      * custom fields). `truncated` is true when more than 250 matched. */
-    listTenants(q) {
-        const qs = q ? `?q=${encodeURIComponent(q)}` : "";
-        return this.request(`/tenants${qs}`);
+    listTenants(q, limit) {
+        return this.request(`/tenants${listQs(q, limit)}`);
     }
     /** Create a tenant and its first owner (system-admin only). */
     createTenant(request) {
@@ -231,38 +256,6 @@ export class UmamiClient {
             body: JSON.stringify(body),
         });
     }
-    patchStatus(tenantId, status) {
-        return this.request(`/tenants/${enc(tenantId)}/status`, {
-            method: "PATCH",
-            body: JSON.stringify({ status }),
-        });
-    }
-    patchLicense(tenantId, body) {
-        return this.request(`/tenants/${enc(tenantId)}/license`, {
-            method: "PATCH",
-            body: JSON.stringify(body),
-        });
-    }
-    getEntitlements(tenantId) {
-        return this.request(`/tenants/${enc(tenantId)}/entitlements`);
-    }
-    assignPackage(tenantId, request) {
-        return this.request(`/tenants/${enc(tenantId)}/packages`, {
-            method: "POST",
-            body: JSON.stringify(request),
-        });
-    }
-    removePackage(tenantId, assignmentId) {
-        return this.request(`/tenants/${enc(tenantId)}/packages/${enc(assignmentId)}`, {
-            method: "DELETE",
-        });
-    }
-    setFeature(tenantId, code, value) {
-        return this.request(`/tenants/${enc(tenantId)}/features/${enc(code)}`, {
-            method: "PUT",
-            body: JSON.stringify({ value }),
-        });
-    }
     // ── authorization: assignable roles/scopes/features + feature grant/revoke ─────
     /** Role codes assignable to a user given their tenant's features (feeds the UI role picker). */
     assignableRoles(userId) {
@@ -288,24 +281,21 @@ export class UmamiClient {
             method: "DELETE",
         });
     }
-    getUsage(tenantId) {
-        return this.request(`/tenants/${enc(tenantId)}/usage`);
-    }
-    incrementUsage(tenantId, metric, amount = 1) {
-        return this.request(`/tenants/${enc(tenantId)}/usage/${enc(metric)}`, {
-            method: "POST",
-            body: JSON.stringify({ amount }),
-        });
-    }
     // ── users ────────────────────────────────────────────────────────────────────
     createUser(request) {
-        return this.request("/users", { method: "POST", body: JSON.stringify(request) });
+        return this.request("/users", {
+            method: "POST",
+            body: JSON.stringify(request),
+        });
     }
     /** List the caller's tenant's users (sorted by recent activity, capped at 250). `q` is an
      * optional case-insensitive search over username / email / name / custom fields. */
-    listUsers(q) {
-        const qs = q ? `?q=${encodeURIComponent(q)}` : "";
-        return this.request(`/users${qs}`);
+    listUsers(q, limit) {
+        return this.request(`/users${listQs(q, limit)}`);
+    }
+    /** Read one user in the caller's tenant (requires `manage:users`). */
+    getUser(userId) {
+        return this.request(`/users/${enc(userId)}`);
     }
     patchUser(userId, body) {
         return this.request(`/users/${enc(userId)}`, {
@@ -333,17 +323,25 @@ export class UmamiClient {
             body: JSON.stringify({ currentPassword, newPassword }),
         });
     }
-    /** The current user's own audit trail (newest first). */
-    async myAudit(limit) {
-        const qs = limit ? `?limit=${limit}` : "";
-        const data = await this.request(`/auth/me/audit${qs}`);
-        return data.entries;
+    /** One page of the current user's own audit trail (newest first). Pass `cursor` to page. */
+    myAudit(limit, cursor) {
+        return this.request(`/auth/me/audit${auditQs(limit, cursor)}`);
+    }
+    /** One page of a tenant's audit trail (requires `admin:tenant`; own tenant). */
+    tenantAudit(tenantId, limit, cursor) {
+        return this.request(`/tenants/${enc(tenantId)}/audit${auditQs(limit, cursor)}`);
     }
-    /** A tenant's audit trail (requires `admin:tenant`; own tenant). */
-    async tenantAudit(tenantId, limit) {
-        const qs = limit ? `?limit=${limit}` : "";
-        const data = await this.request(`/tenants/${enc(tenantId)}/audit${qs}`);
-        return data.entries;
+    /** One page of a tenant user's audit trail (requires `manage:users`; own tenant). */
+    userAudit(userId, limit, cursor) {
+        return this.request(`/users/${enc(userId)}/audit${auditQs(limit, cursor)}`);
+    }
+    /** A tenant user's active login sessions (requires `manage:users`; own tenant). */
+    userSessions(userId) {
+        return this.request(`/users/${enc(userId)}/sessions`);
+    }
+    /** Revokes all of a tenant user's sessions by bumping their tokenVersion (requires `manage:users`). */
+    async logoutUser(userId) {
+        await this.request(`/users/${enc(userId)}/logout-all`, { method: "POST" });
     }
     // ── messaging links ─────────────────────────────────────────────────────────
     /** The caller's current link code (rotated if expired), with deep links when configured. */
@@ -364,6 +362,11 @@ export class UmamiClient {
     deleteMessagingLink(platform, externalId) {
         return this.request(`/auth/me/messaging-links/${enc(platform)}/${enc(externalId)}`, { method: "DELETE" });
     }
+    /** A tenant user's linked identities, read-only (requires `manage:users`; own tenant). */
+    async listUserMessagingLinks(userId) {
+        const data = await this.request(`/users/${enc(userId)}/messaging-links`);
+        return data.links;
+    }
     /** Machine (`messaging:link`): claim a `(platform, externalId)` mapping from a link code. */
     createMessagingLink(code, platform, externalId) {
         return this.request("/messaging/links", {
@@ -423,7 +426,57 @@ export class UmamiClient {
     async deleteMyPat(keyId) {
         await this.request(`/auth/me/api-keys/${enc(keyId)}`, { method: "DELETE" });
     }
+    /** A tenant user's personal access tokens, read-only (requires `manage:users`; own tenant). */
+    async listUserPats(userId) {
+        const data = await this.request(`/users/${enc(userId)}/pats`);
+        return data.keys;
+    }
 }
 function enc(value) {
     return encodeURIComponent(value);
 }
+/** base64url (no padding) of raw bytes. */
+function b64url(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Computes the Mode-2 API-key MAC: `HMAC-SHA256(key = SHA-256(secret), "umami:apikey:<keyId>:<hour>")`,
+ * base64url. The HMAC key is the SHA-256 of the secret — exactly the digest umami stores — so the
+ * server verifies without ever holding the raw secret. Matches `verify_key_hmac` on the server. */
+async function apiKeyMac(keyId, secret) {
+    const subtle = globalThis.crypto.subtle;
+    const enc8 = new TextEncoder();
+    const secretHash = new Uint8Array(await subtle.digest("SHA-256", enc8.encode(secret)));
+    const key = await subtle.importKey("raw", secretHash, { name: "HMAC", hash: "SHA-256" }, false, [
+        "sign",
+    ]);
+    const bucket = Math.floor(Date.now() / 3_600_000); // unix ms → whole hours
+    const mac = await subtle.sign("HMAC", key, enc8.encode(`umami:apikey:${keyId}:${bucket}`));
+    return b64url(new Uint8Array(mac));
+}
+/** Builds a `?limit=&cursor=` query string for the audit endpoints (omitting absent params). */
+function auditQs(limit, cursor) {
+    const params = new URLSearchParams();
+    if (limit != null) {
+        params.set("limit", String(limit));
+    }
+    if (cursor) {
+        params.set("cursor", cursor);
+    }
+    const s = params.toString();
+    return s ? `?${s}` : "";
+}
+/** Builds a `?q=&limit=` query string for the list endpoints (omitting absent params). */
+function listQs(q, limit) {
+    const params = new URLSearchParams();
+    if (q) {
+        params.set("q", q);
+    }
+    if (limit != null) {
+        params.set("limit", String(limit));
+    }
+    const s = params.toString();
+    return s ? `?${s}` : "";
+}