@arbium/enterprise-agent-connect 0.1.1 → 0.1.2-dev.cba5f68

package/dist/connectors/okta/connector.json

@@ -0,0 +1,194 @@
+{
+  "id": "okta",
+  "name": "Okta",
+  "description": "Let agents look up people, groups, apps and sign-in activity in Okta and, if you allow it, help people back in: unlock accounts, send password reset emails, reset MFA, change group membership, suspend or deactivate.",
+  "logo": "/brand/registry/okta.svg",
+  "identity": "An Okta API service app named \"{brand.microsoft.appName}\". It signs in with a key pair, has only the Okta API scopes you grant it, and can act only within the admin role you assign it. Each API key can be kept to the members of chosen groups.",
+  "accountKey": "org",
+  "connectionKind": "guided",
+  "setup": [
+    {
+      "title": "Create an API service app",
+      "body": "In the Okta Admin Console, create an API Services app named \"{brand.microsoft.appName}\". You need a Super Administrator for this and the steps below. Keep its Client ID for the form below.",
+      "link": {
+        "label": "Okta: service app for the Okta API",
+        "href": "https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/"
+      },
+      "click": [
+        "In the Okta Admin Console, go to Applications, then Applications, and select Create App Integration.",
+        "Choose API Services and select Next.",
+        "Name it {brand.microsoft.appName} and select Save.",
+        "On the General tab, copy the Client ID."
+      ]
+    },
+    {
+      "title": "Give it a key pair",
+      "body": "The app signs in with a private key instead of a secret. Okta generates the key and shows the private key only once. Clear the proof-of-possession (DPoP) requirement: the app does not send it.",
+      "click": [
+        "On the app's General tab, under Client Credentials, select Edit.",
+        "For Client authentication choose Public key / Private key, and clear Require Demonstrating Proof of Possession (DPoP) header in token requests.",
+        "Under Public keys select Add key, then Generate new key. Copy the private key (PEM), then select Done.",
+        "Select Save. Copy the KID shown beside the key."
+      ]
+    },
+    {
+      "title": "Grant these Okta API scopes",
+      "body": "On the app's Okta API Scopes tab, grant exactly these and nothing else. The app can do nothing a scope does not cover. With Commands, use an Okta API token of a Super Administrator (Security, then API, then Tokens) and the app's Client ID.",
+      "click": [
+        "Open the app's Okta API Scopes tab.",
+        "Select Grant beside each of {scopes}."
+      ],
+      "copy": [
+        "OKTA=https://your-company.okta.com",
+        "CLIENT_ID=the-client-id",
+        "curl -s -X POST \"$OKTA/api/v1/apps/$CLIENT_ID/grants\" -H \"Authorization: SSWS $OKTA_API_TOKEN\" -H \"Content-Type: application/json\" -d \"{\\\"scopeId\\\": \\\"{scope}\\\", \\\"issuer\\\": \\\"$OKTA\\\"}\""
+      ],
+      "shell": "bash"
+    },
+    {
+      "title": "Assign it an admin role",
+      "body": "Okta also checks the app's admin role on every call, so a scope alone is not enough. Create a custom admin role with the permissions below and a resource set holding the groups agents may work with, then assign both to the app. Okta then refuses anything outside them, whatever an agent asks.",
+      "permissions": true,
+      "click": [
+        "Go to Security, then Administrators, then Roles, and select Create new role. Name it {brand.microsoft.appName}, tick the permissions below and select Save role.",
+        "Under Resources, select Create new resource set, add the groups agents may work with, and save it.",
+        "Open the app's Admin roles tab and select Edit assignments, then Add assignment.",
+        "Choose the role and the resource set you made, and select Save changes."
+      ]
+    }
+  ],
+  "afterConnect": [],
+  "fields": [
+    {
+      "id": "org",
+      "label": "Okta address",
+      "help": "Your Okta organization's address, without -admin.",
+      "placeholder": "your-company.okta.com",
+      "secret": false
+    },
+    {
+      "id": "client_id",
+      "label": "Client ID",
+      "help": "On the app's General tab.",
+      "secret": false
+    },
+    {
+      "id": "key_id",
+      "label": "Key ID (KID)",
+      "help": "Shown beside the key under Public keys. Needed only when the app has more than one key.",
+      "secret": false,
+      "optional": true
+    },
+    {
+      "id": "private_key",
+      "label": "Private key",
+      "help": "The private key Okta showed when it generated the key, PEM or JSON.",
+      "secret": true
+    }
+  ],
+  "capabilities": [
+    {
+      "id": "read",
+      "label": "Look up people and groups",
+      "description": "Find people and read their username, email, title, department, account status, last sign-in, groups and enrolled MFA factors. Find groups and list their members.",
+      "required": true,
+      "note": "Reaches everyone in your Okta organization unless you keep a key to chosen groups under API keys. Read-only.",
+      "scopes": ["okta.users.read", "okta.groups.read"],
+      "permissions": ["View users and their details", "View groups and their details"],
+      "tools": [
+        "okta_get_user",
+        "okta_search_users",
+        "okta_list_factors",
+        "okta_search_groups",
+        "okta_list_group_members"
+      ],
+      "forbidden": "Okta refused this. The app needs {scopes} granted and an admin role that allows it (the Okta page in {brand.productName} shows how)."
+    },
+    {
+      "id": "read_apps",
+      "label": "Look up apps",
+      "description": "List the apps in Okta and the apps assigned to a person.",
+      "scopes": ["okta.apps.read"],
+      "permissions": ["View applications and their details"],
+      "tools": ["okta_list_apps"],
+      "forbidden": "Okta refused this. The app needs {scopes} granted and an admin role that allows it."
+    },
+    {
+      "id": "read_activity",
+      "label": "Read sign-in activity",
+      "description": "Read a person's recent sign-ins, MFA challenges, lockouts and account changes from the System Log, with IP address, place and browser.",
+      "scopes": ["okta.logs.read"],
+      "permissions": ["View the System Log"],
+      "tools": ["okta_get_user_activity"],
+      "forbidden": "Okta refused this. The app needs {scopes} granted and an admin role that allows it."
+    },
+    {
+      "id": "manage_groups",
+      "label": "Change group membership",
+      "description": "Add people to groups and remove them. Membership can give people apps and access.",
+      "note": "With a key kept to chosen groups, agents can only add or remove those groups' members, and only to and from those groups.",
+      "scopes": ["okta.groups.manage"],
+      "permissions": ["Manage group membership"],
+      "tools": ["okta_add_group_member", "okta_remove_group_member"],
+      "forbidden": "Okta refused this. The app needs {scopes} granted and an admin role that allows it."
+    },
+    {
+      "id": "helpdesk",
+      "label": "Unlock accounts and send password resets",
+      "description": "Unlock people who are locked out, and email people a link to set a new password.",
+      "scopes": ["okta.users.manage"],
+      "permissions": ["Unlock users", "Reset users' passwords"],
+      "tools": ["okta_unlock_user", "okta_send_password_reset"],
+      "forbidden": "Okta refused this. The app needs {scopes} granted and an admin role that allows it."
+    },
+    {
+      "id": "reset_mfa",
+      "label": "Reset MFA",
+      "description": "Remove a person's enrolled MFA factor, e.g. after a lost phone. They set it up again at their next sign-in.",
+      "destructive": true,
+      "note": "Until they set it up again, the person signs in without that factor. Okta cannot bring a removed factor back.",
+      "scopes": ["okta.users.manage"],
+      "permissions": ["Reset users' authenticators"],
+      "tools": ["okta_reset_factor"],
+      "forbidden": "Okta refused this. The app needs {scopes} granted and an admin role that allows it."
+    },
+    {
+      "id": "suspend",
+      "label": "Suspend people and sign them out",
+      "description": "Suspend and unsuspend people, and sign people out of every session.",
+      "destructive": true,
+      "note": "A suspended or signed-out person cannot work until someone lets them back in.",
+      "scopes": ["okta.users.manage"],
+      "permissions": ["Suspend users", "Unsuspend users", "Clear users' sessions"],
+      "tools": ["okta_suspend_user", "okta_unsuspend_user", "okta_clear_sessions"],
+      "forbidden": "Okta refused this. The app needs {scopes} granted and an admin role that allows it."
+    },
+    {
+      "id": "deactivate",
+      "label": "Deactivate people",
+      "description": "Deactivate people: they can no longer sign in, and apps set up for it remove their accounts.",
+      "destructive": true,
+      "note": "Deactivating can remove a person's accounts in other apps. Only an administrator can reactivate them, and removed app accounts may not come back.",
+      "scopes": ["okta.users.manage"],
+      "permissions": ["Deactivate users"],
+      "tools": ["okta_deactivate_user"],
+      "forbidden": "Okta refused this. The app needs {scopes} granted and an admin role that allows it."
+    }
+  ],
+  "limits": [
+    {
+      "id": "groups",
+      "label": "Groups",
+      "help": "Optional: only people in these groups (their ids, 00g..., from the group's address in the Okta Admin Console), and only these groups. Leave empty for everyone.",
+      "kind": "list",
+      "required": false,
+      "pattern": "^00g[A-Za-z0-9]{17}$"
+    }
+  ],
+  "verify": {
+    "label": "Okta API scopes the app has",
+    "check": "scopes",
+    "ifEmpty": "The app has none of the Okta API scopes needed yet. Grant them on its Okta API Scopes tab."
+  },
+  "revoke": "In the Okta Admin Console, open Applications, then {brand.microsoft.appName}, and deactivate it, or remove its key or its Okta API scopes. Agents lose access to Okta at once."
+}

package/dist/connectors/okta/index.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    id: string;
+    create: () => {
+        vendor: import("../../packages/connector-kit/src/types.js").Vendor;
+        toolset: import("../../packages/connector-kit/src/common.js").Toolset;
+    };
+};
+export default _default;

package/dist/connectors/okta/index.js

@@ -0,0 +1,7 @@
+import { oktaTools } from "./tools.js";
+import { oktaVendor } from "./vendor.js";
+export default {
+    id: "okta",
+    create: () => ({ vendor: oktaVendor(), toolset: oktaTools }),
+};
+//# sourceMappingURL=index.js.map

package/dist/connectors/okta/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../connectors/okta/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,eAAe;IACb,EAAE,EAAE,MAAM;IACV,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;CACnC,CAAC"}

package/dist/connectors/okta/tools.d.ts

@@ -0,0 +1,6 @@
+import { type ToolContext, type Toolset } from "../../packages/connector-kit/src/common.js";
+export declare const MAX_GROUP_PAGES = 5;
+export declare const MAX_SCOPED_PAGES = 5;
+/** The key's group ids; null when it has none. */
+export declare function groupScope(ctx: ToolContext): Set<string> | null;
+export declare const oktaTools: Toolset;

package/dist/connectors/okta/tools.js

@@ -0,0 +1,429 @@
+import { z } from "zod";
+import { audited, Denied, json, listLimit, VendorFailed, } from "../../packages/connector-kit/src/common.js";
+import { cursorArg } from "../sharepoint-files/tools.js";
+// People, groups, apps and sign-in activity in Okta, and the help desk's actions on a person.
+// A key's `groups` limit (Okta group ids) keeps it to the members of those groups: every tool
+// that names a person reads the person's groups first, and every write checks before it calls.
+// Okta has no nested groups, so membership is direct. Request shapes: developer.okta.com/docs/
+// api/openapi/okta-management/management/tag/User, UserLifecycle, UserSessions, UserFactor,
+// Group, Application and SystemLog (read October 27, 2026).
+const USER_ID = /^00u[A-Za-z0-9]{17}$/;
+const GROUP_ID = /^00g[A-Za-z0-9]{17}$/;
+const FACTOR_ID = /^[A-Za-z0-9]{20}$/;
+const LOGIN = /^[^\s/\\?#%"]{1,100}$/;
+const EVENT_TYPE = /^[a-z0-9_.]{1,100}$/;
+const STATUSES = [
+    "ACTIVE",
+    "LOCKED_OUT",
+    "PASSWORD_EXPIRED",
+    "RECOVERY",
+    "SUSPENDED",
+    "PROVISIONED",
+    "STAGED",
+    "DEPROVISIONED",
+];
+// A person's groups are read at most this many pages of 200 for the limit check; past it the
+// person reads as outside the key's groups (refused, never widened).
+export const MAX_GROUP_PAGES = 5;
+// Under a groups limit a search reads on, at most this many pages, until it has `max_results`.
+export const MAX_SCOPED_PAGES = 5;
+// Okta keeps the System Log 90 days.
+const MAX_HOURS = 90 * 24;
+function oktaError(res) {
+    const d = res.data;
+    const detail = [d?.errorSummary, ...(d?.errorCauses ?? []).map((c) => c.errorSummary)]
+        .filter(Boolean)
+        .join("; ");
+    return new VendorFailed(res.status, `Okta answered ${res.status}${detail ? `: ${detail}` : ""}`);
+}
+async function ok(ctx, mark, req) {
+    const res = await ctx.call(req);
+    mark(res.status);
+    if (res.status < 200 || res.status >= 300)
+        throw oktaError(res);
+    return res.data;
+}
+const page = (ctx, mark, path) => ok(ctx, mark, { method: "GET", path });
+const after = (cursor) => cursor ? `&after=${encodeURIComponent(cursor)}` : "";
+/** The key's group ids; null when it has none. */
+export function groupScope(ctx) {
+    const groups = listLimit(ctx.limits, "groups");
+    return groups ? new Set(groups) : null;
+}
+async function groupsOf(ctx, mark, userId) {
+    const groups = [];
+    let cursor = null;
+    for (let read = 0; read < MAX_GROUP_PAGES; read++) {
+        const data = await page(ctx, mark, `/api/v1/users/${userId}/groups?limit=200${after(cursor)}`);
+        groups.push(...data.items);
+        cursor = data.after;
+        if (!cursor)
+            break;
+    }
+    return groups;
+}
+const inScope = (scope, groups) => !scope || groups.some((g) => scope.has(g.id));
+function userRef(raw) {
+    const value = raw.trim();
+    if (!USER_ID.test(value) && !LOGIN.test(value))
+        throw new Denied("Give a person's Okta id or username, such as ada@acme.com");
+    return encodeURIComponent(value);
+}
+/** The person, read and checked against the key's groups; `groups` only when read. */
+async function openUser(ctx, mark, raw, withGroups = false) {
+    const scope = groupScope(ctx);
+    const denied = new Denied("This agent may not look up or act on that person");
+    let user;
+    try {
+        user = await ok(ctx, mark, { method: "GET", path: `/api/v1/users/${userRef(raw)}` });
+    }
+    catch (error) {
+        // A kept key must not learn which usernames exist outside its groups.
+        if (scope && error instanceof VendorFailed && error.status === 404)
+            throw denied;
+        throw error;
+    }
+    if (!USER_ID.test(user.id ?? ""))
+        throw new Error("Okta answered a user without an id");
+    const groups = scope || withGroups ? await groupsOf(ctx, mark, user.id) : [];
+    if (!inScope(scope, groups))
+        throw denied;
+    return { user, groups, scope };
+}
+const person = (u) => ({
+    id: u.id,
+    login: u.profile?.login ?? null,
+    email: u.profile?.email ?? null,
+    name: [u.profile?.firstName, u.profile?.lastName].filter(Boolean).join(" ") || null,
+    title: u.profile?.title ?? null,
+    department: u.profile?.department ?? null,
+    status: u.status ?? null,
+});
+const group = (g) => ({
+    id: g.id,
+    name: g.profile?.name ?? null,
+    description: g.profile?.description ?? null,
+    type: g.type ?? null,
+});
+/** A listing page kept to what `keep` allows; `next` continues after the last page read. */
+async function keptPage(ctx, mark, path, max, cursor, scoped, keep) {
+    const kept = [];
+    let next = cursor ?? null;
+    for (let read = 0; read < (scoped ? MAX_SCOPED_PAGES : 1); read++) {
+        const data = await page(ctx, mark, path(after(next)));
+        for (const item of await Promise.all(data.items.map(keep)))
+            if (item !== null)
+                kept.push(item);
+        next = data.after;
+        if (!next || kept.length >= max)
+            break;
+    }
+    return { kept, more: Boolean(next), next };
+}
+// Search words go inside Okta's quoted filter strings.
+const words = (raw) => raw.replace(/["\\]/g, "").trim();
+// The log window rides in the cursor, so a later page reads the same window.
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+function logWindow(cursor) {
+    if (!cursor)
+        return { until: new Date().toISOString(), after: null };
+    const split = cursor.indexOf("~");
+    const [until, rest] = [cursor.slice(0, split), cursor.slice(split + 1)];
+    if (split < 0 || !ISO.test(until) || !rest)
+        throw new Denied("Give `next` from the previous call as `cursor`");
+    return { until, after: rest };
+}
+function event(e, userId, scoped) {
+    const actor = e.actor ?? {};
+    const ua = e.client?.userAgent ?? {};
+    const geo = e.client?.geographicalContext ?? {};
+    const known = (v) => (typeof v === "string" && v && v !== "UNKNOWN" ? v : null);
+    return {
+        time: e.published ?? null,
+        event_type: e.eventType ?? null,
+        message: e.displayMessage ?? null,
+        outcome: e.outcome?.result ?? null,
+        reason: e.outcome?.reason ?? null,
+        // Under a groups limit another person's name could be outside the key's groups.
+        by: actor.id === userId
+            ? "this person"
+            : scoped && actor.type === "User"
+                ? "another person"
+                : (actor.displayName ?? null),
+        ip: e.client?.ipAddress ?? null,
+        location: [geo.city, geo.state, geo.country].filter(known).join(", ") || null,
+        client: [known(ua.browser), known(ua.os)].filter(Boolean).join(" on ") || null,
+    };
+}
+export const oktaTools = {
+    names: [
+        "okta_get_user",
+        "okta_search_users",
+        "okta_list_factors",
+        "okta_search_groups",
+        "okta_list_group_members",
+        "okta_list_apps",
+        "okta_get_user_activity",
+        "okta_add_group_member",
+        "okta_remove_group_member",
+        "okta_unlock_user",
+        "okta_send_password_reset",
+        "okta_reset_factor",
+        "okta_suspend_user",
+        "okta_unsuspend_user",
+        "okta_clear_sessions",
+        "okta_deactivate_user",
+    ],
+    register(server, ctx, allowed) {
+        const readOnly = { readOnlyHint: true, openWorldHint: true };
+        const write = (destructive) => ({ readOnlyHint: false, destructiveHint: destructive, openWorldHint: true });
+        const user = z
+            .string()
+            .max(100)
+            .describe("A person's Okta id (00u...) or username, such as ada@acme.com.");
+        const groupId = z.string().max(20).describe("A group's id (00g...), from okta_search_groups.");
+        const max = (most, fallback) => z.number().int().min(1).max(most).default(fallback);
+        const checkGroup = (scope, id) => {
+            if (!GROUP_ID.test(id))
+                throw new Denied("Give a group id from okta_search_groups");
+            if (scope && !scope.has(id))
+                throw new Denied("This agent may not use that group");
+        };
+        if (allowed.has("okta_get_user"))
+            server.registerTool("okta_get_user", {
+                description: "Look up one person: username, email, name, title, department, account status (ACTIVE, LOCKED_OUT, SUSPENDED, PASSWORD_EXPIRED, ...), last sign-in, last password change and their groups.",
+                inputSchema: z.object({ user }),
+                annotations: readOnly,
+            }, ({ user: u }) => audited(ctx, "okta_get_user", u, async (mark) => {
+                const { user: p, groups, scope } = await openUser(ctx, mark, u, true);
+                const shown = groups.filter((g) => !scope || scope.has(g.id));
+                return json({
+                    ...person(p),
+                    locked_out: p.status === "LOCKED_OUT",
+                    last_login: p.lastLogin ?? null,
+                    password_changed: p.passwordChanged ?? null,
+                    status_changed: p.statusChanged ?? null,
+                    created: p.created ?? null,
+                    groups: shown.slice(0, 100).map(group),
+                    more_groups: shown.length > 100,
+                });
+            }));
+        if (allowed.has("okta_search_users"))
+            server.registerTool("okta_search_users", {
+                description: "Find people whose username, email, first or last name starts with `query`, or everyone with a status (e.g. LOCKED_OUT). When `more` is true, call again with `cursor` set to `next`.",
+                inputSchema: z.object({
+                    query: z.string().max(100).optional(),
+                    status: z.enum(STATUSES).optional(),
+                    max_results: max(50, 25),
+                    cursor: cursorArg,
+                }),
+                annotations: readOnly,
+            }, ({ query, status, max_results, cursor }) => audited(ctx, "okta_search_users", query ?? status ?? null, async (mark) => {
+                const w = words(query ?? "");
+                if (!w && !status)
+                    throw new Denied("Give a few letters of a name, or a status");
+                const parts = [
+                    ...(w
+                        ? [
+                            `(${["login", "email", "firstName", "lastName"].map((f) => `profile.${f} sw "${w}"`).join(" or ")})`,
+                        ]
+                        : []),
+                    ...(status ? [`status eq "${status}"`] : []),
+                ];
+                const search = encodeURIComponent(parts.join(" and "));
+                const scope = groupScope(ctx);
+                const { kept, more, next } = await keptPage(ctx, mark, (c) => `/api/v1/users?search=${search}&limit=${max_results}${c}`, max_results, cursor, Boolean(scope), async (u) => inScope(scope, scope ? await groupsOf(ctx, mark, u.id) : []) ? person(u) : null);
+                return json({ people: kept, more, next });
+            }));
+        if (allowed.has("okta_list_factors"))
+            server.registerTool("okta_list_factors", {
+                description: "List a person's enrolled MFA factors (authenticators): id, type, provider and status. Use an id with okta_reset_factor.",
+                inputSchema: z.object({ user }),
+                annotations: readOnly,
+            }, ({ user: u }) => audited(ctx, "okta_list_factors", u, async (mark) => {
+                const { user: p } = await openUser(ctx, mark, u);
+                const data = await page(ctx, mark, `/api/v1/users/${p.id}/factors`);
+                return json({
+                    user: person(p),
+                    factors: data.items.map((f) => ({
+                        id: f.id,
+                        type: f.factorType ?? null,
+                        provider: f.provider ?? null,
+                        name: f.vendorName ?? null,
+                        status: f.status ?? null,
+                        enrolled: f.created ?? null,
+                        last_updated: f.lastUpdated ?? null,
+                    })),
+                });
+            }));
+        if (allowed.has("okta_search_groups"))
+            server.registerTool("okta_search_groups", {
+                description: "Find groups whose name starts with `query` (all groups without it). When `more` is true, call again with `cursor` set to `next`.",
+                inputSchema: z.object({
+                    query: z.string().max(100).optional(),
+                    max_results: max(100, 25),
+                    cursor: cursorArg,
+                }),
+                annotations: readOnly,
+            }, ({ query, max_results, cursor }) => audited(ctx, "okta_search_groups", query ?? null, async (mark) => {
+                const w = words(query ?? "");
+                const scope = groupScope(ctx);
+                if (scope) {
+                    // The key's own groups, read directly: scanning every group to find them could miss.
+                    const found = await Promise.all([...scope].map(async (id) => {
+                        const res = await ctx.call({ method: "GET", path: `/api/v1/groups/${id}` });
+                        mark(res.status);
+                        if (res.status === 404)
+                            return null;
+                        if (res.status < 200 || res.status >= 300)
+                            throw oktaError(res);
+                        return res.data;
+                    }));
+                    const groups = found
+                        .filter((g) => g !== null)
+                        .filter((g) => (g.profile?.name ?? "").toLowerCase().startsWith(w.toLowerCase()))
+                        .map(group);
+                    return json({ groups, more: false, next: null });
+                }
+                const data = await page(ctx, mark, `/api/v1/groups?${w ? `q=${encodeURIComponent(w)}&` : ""}limit=${max_results}${after(cursor)}`);
+                return json({
+                    groups: data.items.map(group),
+                    more: Boolean(data.after),
+                    next: data.after,
+                });
+            }));
+        if (allowed.has("okta_list_group_members"))
+            server.registerTool("okta_list_group_members", {
+                description: "List the people in a group. When `more` is true, call again with `cursor` set to `next`.",
+                inputSchema: z.object({
+                    group_id: groupId,
+                    max_results: max(200, 50),
+                    cursor: cursorArg,
+                }),
+                annotations: readOnly,
+            }, ({ group_id, max_results, cursor }) => audited(ctx, "okta_list_group_members", group_id, async (mark) => {
+                checkGroup(groupScope(ctx), group_id);
+                const data = await page(ctx, mark, `/api/v1/groups/${group_id}/users?limit=${max_results}${after(cursor)}`);
+                return json({
+                    people: data.items.map(person),
+                    more: Boolean(data.after),
+                    next: data.after,
+                });
+            }));
+        if (allowed.has("okta_list_apps"))
+            server.registerTool("okta_list_apps", {
+                description: "List apps in Okta: those assigned to `user` when given, and with a name starting with `query` when given. When `more` is true, call again with `cursor` set to `next`.",
+                inputSchema: z.object({
+                    user: user.optional(),
+                    query: z.string().max(100).optional(),
+                    max_results: max(100, 25),
+                    cursor: cursorArg,
+                }),
+                annotations: readOnly,
+            }, ({ user: u, query, max_results, cursor }) => audited(ctx, "okta_list_apps", u ?? query ?? null, async (mark) => {
+                const w = words(query ?? "");
+                const filter = u
+                    ? `filter=${encodeURIComponent(`user.id eq "${(await openUser(ctx, mark, u)).user.id}"`)}&`
+                    : "";
+                const q = w ? `q=${encodeURIComponent(w)}&` : "";
+                const data = await page(ctx, mark, `/api/v1/apps?${filter}${q}limit=${max_results}${after(cursor)}`);
+                return json({
+                    apps: data.items.map((a) => ({
+                        id: a.id,
+                        label: a.label ?? null,
+                        app: a.name ?? null,
+                        status: a.status ?? null,
+                        sign_on_mode: a.signOnMode ?? null,
+                    })),
+                    more: Boolean(data.after),
+                    next: data.after,
+                });
+            }));
+        if (allowed.has("okta_get_user_activity"))
+            server.registerTool("okta_get_user_activity", {
+                description: "A person's recent System Log events, newest first: sign-ins, MFA challenges, lockouts, password and account changes, with outcome, IP address, place and browser. Also gives their status and last sign-in. `event_type` narrows to one Okta event type, e.g. user.session.start or user.account.lock. When `more` is true, call again with `cursor` set to `next` and the same `hours`.",
+                inputSchema: z.object({
+                    user,
+                    hours: z.number().int().min(1).max(MAX_HOURS).default(24),
+                    event_type: z.string().max(100).optional(),
+                    max_results: max(100, 25),
+                    cursor: cursorArg,
+                }),
+                annotations: readOnly,
+            }, ({ user: u, hours, event_type, max_results, cursor }) => audited(ctx, "okta_get_user_activity", u, async (mark) => {
+                if (event_type !== undefined && !EVENT_TYPE.test(event_type))
+                    throw new Denied("Give an Okta event type such as user.session.start");
+                const window = logWindow(cursor);
+                const { user: p, scope } = await openUser(ctx, mark, u);
+                const since = new Date(Date.parse(window.until) - hours * 3600_000).toISOString();
+                const filter = `(actor.id eq "${p.id}" or target.id eq "${p.id}")${event_type ? ` and eventType eq "${event_type}"` : ""}`;
+                const data = await page(ctx, mark, `/api/v1/logs?since=${since}&until=${window.until}&sortOrder=DESCENDING&filter=${encodeURIComponent(filter)}&limit=${max_results}${after(window.after)}`);
+                return json({
+                    user: person(p),
+                    last_login: p.lastLogin ?? null,
+                    events: data.items.map((e) => event(e, p.id, Boolean(scope))),
+                    more: Boolean(data.after),
+                    next: data.after ? `${window.until}~${data.after}` : null,
+                });
+            }));
+        const membership = (tool, add) => server.registerTool(tool, {
+            description: add
+                ? "Add a person to a group. Membership can give them apps and access."
+                : "Remove a person from a group. They lose what the group gave them.",
+            inputSchema: z.object({ user, group_id: groupId }),
+            annotations: write(false),
+        }, ({ user: u, group_id }) => audited(ctx, tool, `${u} ${add ? "to" : "from"} ${group_id}`, async (mark) => {
+            checkGroup(groupScope(ctx), group_id);
+            const { user: p } = await openUser(ctx, mark, u);
+            await ok(ctx, mark, {
+                method: add ? "PUT" : "DELETE",
+                path: `/api/v1/groups/${group_id}/users/${p.id}`,
+            });
+            return json({ user: person(p), group_id, member: add });
+        }));
+        if (allowed.has("okta_add_group_member"))
+            membership("okta_add_group_member", true);
+        if (allowed.has("okta_remove_group_member"))
+            membership("okta_remove_group_member", false);
+        // One action on one person: read and checked first, then the call on their id.
+        const action = (tool, description, destructive, path, done) => server.registerTool(tool, { description, inputSchema: z.object({ user }), annotations: write(destructive) }, ({ user: u }) => audited(ctx, tool, u, async (mark) => {
+            const { user: p } = await openUser(ctx, mark, u);
+            await ok(ctx, mark, path(p.id));
+            return json({ user: person(p), done });
+        }));
+        const lifecycle = (id, step, query = "") => ({
+            method: "POST",
+            path: `/api/v1/users/${id}/lifecycle/${step}${query}`,
+        });
+        if (allowed.has("okta_unlock_user"))
+            action("okta_unlock_user", "Unlock a person whose account is locked out (status LOCKED_OUT) so they can sign in again with their password.", false, (id) => lifecycle(id, "unlock"), "Unlocked");
+        if (allowed.has("okta_send_password_reset"))
+            action("okta_send_password_reset", "Email a person a link to set a new password. Their current password stops working until they do. The link goes only to them.", false, 
+            // Always emailed: without sendEmail Okta would answer the reset link itself.
+            (id) => lifecycle(id, "reset_password", "?sendEmail=true"), "Okta emailed them a password reset link");
+        if (allowed.has("okta_suspend_user"))
+            action("okta_suspend_user", "Suspend a person: they cannot sign in until unsuspended. Their apps and groups are kept.", true, (id) => lifecycle(id, "suspend"), "Suspended");
+        if (allowed.has("okta_unsuspend_user"))
+            action("okta_unsuspend_user", "Unsuspend a suspended person so they can sign in again.", false, (id) => lifecycle(id, "unsuspend"), "Unsuspended");
+        if (allowed.has("okta_clear_sessions"))
+            action("okta_clear_sessions", "Sign a person out everywhere: ends their Okta sessions and revokes the tokens apps got through Okta.", true, (id) => ({ method: "DELETE", path: `/api/v1/users/${id}/sessions?oauthTokens=true` }), "Signed out everywhere");
+        if (allowed.has("okta_deactivate_user"))
+            action("okta_deactivate_user", "Deactivate a person: they can no longer sign in, and apps set up for it remove their accounts. Only an administrator can reactivate them.", true, (id) => lifecycle(id, "deactivate", "?sendEmail=false"), "Deactivated");
+        if (allowed.has("okta_reset_factor"))
+            server.registerTool("okta_reset_factor", {
+                description: "Remove one of a person's MFA factors (id from okta_list_factors), e.g. after a lost phone. They set it up again at their next sign-in.",
+                inputSchema: z.object({ user, factor_id: z.string().max(20) }),
+                annotations: write(true),
+            }, ({ user: u, factor_id }) => audited(ctx, "okta_reset_factor", `${u} factor ${factor_id}`, async (mark) => {
+                if (!FACTOR_ID.test(factor_id))
+                    throw new Denied("Give a factor id from okta_list_factors");
+                const { user: p } = await openUser(ctx, mark, u);
+                await ok(ctx, mark, {
+                    method: "DELETE",
+                    path: `/api/v1/users/${p.id}/factors/${factor_id}`,
+                });
+                return json({ user: person(p), factor_id, done: "Factor removed" });
+            }));
+    },
+};
+//# sourceMappingURL=tools.js.map