@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/scim/routes.js

@@ -0,0 +1,249 @@
+// SCIM 2.0 routes — mounted at /scim/v2/.
+//
+// Spec subset covered:
+//   GET    /scim/v2/ServiceProviderConfig
+//   GET    /scim/v2/ResourceTypes
+//   GET    /scim/v2/Schemas
+//   GET    /scim/v2/Users        list (no filter support yet)
+//   GET    /scim/v2/Users/:id
+//   POST   /scim/v2/Users
+//   PATCH  /scim/v2/Users/:id    minimal: replace top-level attrs
+//   DELETE /scim/v2/Users/:id
+//   GET    /scim/v2/Groups
+//   GET    /scim/v2/Groups/:id
+//   POST   /scim/v2/Groups
+//   PATCH  /scim/v2/Groups/:id
+//   DELETE /scim/v2/Groups/:id
+//
+// Auth: Bearer token via OMCP_SCIM_TOKEN; absence of OMCP_SCIM_TOKEN
+// rejects every request (the routes are not safe without it).
+import { timingSafeEqual } from "node:crypto";
+import { SCIM_SCHEMA_LIST_RESPONSE, SCIM_SCHEMA_USER, SCIM_SCHEMA_GROUP, scimError, } from "./types.js";
+import { ScimNotFoundError, ScimValidationError } from "./store.js";
+const constantTimeBearerMatch = (raw, expected) => {
+    if (!raw)
+        return false;
+    const m = raw.match(/^Bearer\s+(.+)$/i);
+    if (!m)
+        return false;
+    const a = Buffer.from(m[1].trim());
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+};
+export function registerScimRoutes(app, deps) {
+    const { store, bearerToken, audit } = deps;
+    // Auth middleware — scoped to /scim/v2/* only.
+    app.use("/scim/v2", (req, res, next) => {
+        if (!bearerToken) {
+            res.status(503).json(scimError(503, "SCIM is enabled but OMCP_SCIM_TOKEN is unset"));
+            return;
+        }
+        if (!constantTimeBearerMatch(req.headers["authorization"], bearerToken)) {
+            res.status(401).json(scimError(401, "valid SCIM bearer token required"));
+            return;
+        }
+        next();
+    });
+    // ---- Discovery endpoints ----
+    app.get("/scim/v2/ServiceProviderConfig", (_req, res) => {
+        res.json({
+            schemas: ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
+            documentationUri: "https://thotischner.github.io/observability-mcp/scim-provisioning/",
+            patch: { supported: true },
+            bulk: { supported: false, maxOperations: 0, maxPayloadSize: 0 },
+            filter: { supported: false, maxResults: 200 },
+            changePassword: { supported: false },
+            sort: { supported: false },
+            etag: { supported: false },
+            authenticationSchemes: [
+                {
+                    name: "OAuth Bearer Token",
+                    description: "Authentication via OAuth 2.0 bearer token (configured per-deployment).",
+                    specUri: "https://datatracker.ietf.org/doc/html/rfc6750",
+                    documentationUri: "https://thotischner.github.io/observability-mcp/scim-provisioning/",
+                    type: "oauthbearertoken",
+                    primary: true,
+                },
+            ],
+        });
+    });
+    app.get("/scim/v2/ResourceTypes", (_req, res) => {
+        res.json({
+            schemas: [SCIM_SCHEMA_LIST_RESPONSE],
+            totalResults: 2,
+            Resources: [
+                {
+                    schemas: ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
+                    id: "User",
+                    name: "User",
+                    endpoint: "/Users",
+                    description: "User account",
+                    schema: SCIM_SCHEMA_USER,
+                },
+                {
+                    schemas: ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
+                    id: "Group",
+                    name: "Group",
+                    endpoint: "/Groups",
+                    description: "Group / role mapping",
+                    schema: SCIM_SCHEMA_GROUP,
+                },
+            ],
+        });
+    });
+    app.get("/scim/v2/Schemas", (_req, res) => {
+        res.json({
+            schemas: [SCIM_SCHEMA_LIST_RESPONSE],
+            totalResults: 2,
+            Resources: [
+                { schemas: ["urn:ietf:params:scim:schemas:core:2.0:Schema"], id: SCIM_SCHEMA_USER, name: "User" },
+                { schemas: ["urn:ietf:params:scim:schemas:core:2.0:Schema"], id: SCIM_SCHEMA_GROUP, name: "Group" },
+            ],
+        });
+    });
+    // ---- Users ----
+    app.get("/scim/v2/Users", (_req, res) => {
+        const users = store.listUsers().map((u) => withGroups(u, store));
+        res.json({
+            schemas: [SCIM_SCHEMA_LIST_RESPONSE],
+            totalResults: users.length,
+            itemsPerPage: users.length,
+            startIndex: 1,
+            Resources: users,
+        });
+    });
+    app.get("/scim/v2/Users/:id", (req, res) => {
+        const u = store.getUser(req.params.id);
+        if (!u) {
+            res.status(404).json(scimError(404, `User ${req.params.id} not found`));
+            return;
+        }
+        res.json(withGroups(u, store));
+    });
+    app.post("/scim/v2/Users", async (req, res) => {
+        try {
+            const u = await store.createUser((req.body ?? {}));
+            audit?.({ actor: "scim", action: "User.create", target: u.userName, result: "ok", status: 201 });
+            res.status(201).json(withGroups(u, store));
+        }
+        catch (e) {
+            handleStoreError(e, res, "User.create", audit);
+        }
+    });
+    app.patch("/scim/v2/Users/:id", async (req, res) => {
+        try {
+            const patch = applyPatchOps(store.getUser(req.params.id), req.body);
+            const u = await store.updateUser(req.params.id, patch);
+            audit?.({ actor: "scim", action: "User.update", target: u.userName, result: "ok", status: 200 });
+            res.json(withGroups(u, store));
+        }
+        catch (e) {
+            handleStoreError(e, res, "User.update", audit);
+        }
+    });
+    app.delete("/scim/v2/Users/:id", async (req, res) => {
+        const ok = await store.deleteUser(req.params.id);
+        audit?.({ actor: "scim", action: "User.delete", target: req.params.id, result: ok ? "ok" : "error", status: ok ? 204 : 404 });
+        if (!ok) {
+            res.status(404).json(scimError(404, `User ${req.params.id} not found`));
+            return;
+        }
+        res.status(204).end();
+    });
+    // ---- Groups ----
+    app.get("/scim/v2/Groups", (_req, res) => {
+        const groups = store.listGroups();
+        res.json({
+            schemas: [SCIM_SCHEMA_LIST_RESPONSE],
+            totalResults: groups.length,
+            itemsPerPage: groups.length,
+            startIndex: 1,
+            Resources: groups,
+        });
+    });
+    app.get("/scim/v2/Groups/:id", (req, res) => {
+        const g = store.getGroup(req.params.id);
+        if (!g) {
+            res.status(404).json(scimError(404, `Group ${req.params.id} not found`));
+            return;
+        }
+        res.json(g);
+    });
+    app.post("/scim/v2/Groups", async (req, res) => {
+        try {
+            const g = await store.createGroup((req.body ?? {}));
+            audit?.({ actor: "scim", action: "Group.create", target: g.displayName, result: "ok", status: 201 });
+            res.status(201).json(g);
+        }
+        catch (e) {
+            handleStoreError(e, res, "Group.create", audit);
+        }
+    });
+    app.patch("/scim/v2/Groups/:id", async (req, res) => {
+        try {
+            const patch = applyPatchOps(store.getGroup(req.params.id), req.body);
+            const g = await store.updateGroup(req.params.id, patch);
+            audit?.({ actor: "scim", action: "Group.update", target: g.displayName, result: "ok", status: 200 });
+            res.json(g);
+        }
+        catch (e) {
+            handleStoreError(e, res, "Group.update", audit);
+        }
+    });
+    app.delete("/scim/v2/Groups/:id", async (req, res) => {
+        const ok = await store.deleteGroup(req.params.id);
+        audit?.({ actor: "scim", action: "Group.delete", target: req.params.id, result: ok ? "ok" : "error", status: ok ? 204 : 404 });
+        if (!ok) {
+            res.status(404).json(scimError(404, `Group ${req.params.id} not found`));
+            return;
+        }
+        res.status(204).end();
+    });
+}
+function withGroups(u, store) {
+    return { ...u, groups: store.groupsContaining(u.id) };
+}
+/** Translate a SCIM PatchOp into a partial resource patch. Minimal:
+ *  we accept `op: "replace"` with no path (whole-resource merge) or
+ *  with a single-segment path naming a top-level attribute. `add` and
+ *  `remove` for members/emails arrays are a follow-up — the
+ *  Entra/Okta provisioning checklists exercise replace-only on the
+ *  attributes we expose. */
+function applyPatchOps(current, patch) {
+    if (!current)
+        throw new ScimNotFoundError("target resource not found");
+    if (!patch?.Operations || !Array.isArray(patch.Operations))
+        return {};
+    const out = {};
+    for (const op of patch.Operations) {
+        if (op.op !== "replace")
+            continue; // skip add/remove for F21a
+        if (!op.path) {
+            // value is a partial object — merge top-level keys
+            if (op.value && typeof op.value === "object") {
+                Object.assign(out, op.value);
+            }
+            continue;
+        }
+        out[op.path] = op.value;
+    }
+    return out;
+}
+function handleStoreError(e, res, action, audit) {
+    if (e instanceof ScimNotFoundError) {
+        audit?.({ actor: "scim", action, target: "?", result: "error", status: 404 });
+        res.status(404).json(scimError(404, e.message));
+        return;
+    }
+    if (e instanceof ScimValidationError) {
+        const status = e.scimType === "uniqueness" ? 409 : 400;
+        audit?.({ actor: "scim", action, target: "?", result: "error", status });
+        res.status(status).json(scimError(status, e.message, e.scimType));
+        return;
+    }
+    console.warn(`[scim] ${action} failed:`, e);
+    audit?.({ actor: "scim", action, target: "?", result: "error", status: 500 });
+    res.status(500).json(scimError(500, "internal error"));
+}

package/dist/scim/store.d.ts

@@ -0,0 +1,37 @@
+import { type ScimGroup, type ScimUser } from "./types.js";
+export interface ScimSnapshot {
+    users: ScimUser[];
+    groups: ScimGroup[];
+}
+export declare class ScimStore {
+    private readonly path;
+    private snapshot;
+    private bootstrapped;
+    constructor(path: string);
+    load(): Promise<void>;
+    listUsers(): ScimUser[];
+    getUser(id: string): ScimUser | undefined;
+    getUserByUserName(userName: string): ScimUser | undefined;
+    createUser(input: Partial<ScimUser>): Promise<ScimUser>;
+    updateUser(id: string, patch: Partial<ScimUser>): Promise<ScimUser>;
+    deleteUser(id: string): Promise<boolean>;
+    listGroups(): ScimGroup[];
+    getGroup(id: string): ScimGroup | undefined;
+    createGroup(input: Partial<ScimGroup>): Promise<ScimGroup>;
+    updateGroup(id: string, patch: Partial<ScimGroup>): Promise<ScimGroup>;
+    deleteGroup(id: string): Promise<boolean>;
+    /** Look up the groups a user is currently a member of — used to
+     *  populate `User.groups` on read responses. */
+    groupsContaining(userId: string): Array<{
+        value: string;
+        display?: string;
+    }>;
+    private persist;
+}
+export declare class ScimValidationError extends Error {
+    readonly scimType?: string | undefined;
+    constructor(message: string, scimType?: string | undefined);
+}
+export declare class ScimNotFoundError extends Error {
+    constructor(message: string);
+}

package/dist/scim/store.js

@@ -0,0 +1,178 @@
+// SCIM store — file-backed JSON for users + groups.
+//
+// F21a uses an on-disk JSON file (atomic tmp+rename, mode 0600).
+// Multi-replica deployments should plug the F8 SessionStore in here
+// — that's F21b. The interface intentionally mirrors what the
+// SessionStore exposes so the swap is purely additive.
+import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { nowIso, SCIM_SCHEMA_GROUP, SCIM_SCHEMA_USER } from "./types.js";
+const EMPTY = { users: [], groups: [] };
+export class ScimStore {
+    path;
+    snapshot = EMPTY;
+    bootstrapped = null;
+    constructor(path) {
+        this.path = path;
+    }
+    async load() {
+        if (this.bootstrapped)
+            return this.bootstrapped;
+        this.bootstrapped = (async () => {
+            try {
+                const raw = await readFile(this.path, "utf8");
+                const parsed = JSON.parse(raw);
+                this.snapshot = {
+                    users: Array.isArray(parsed.users) ? parsed.users : [],
+                    groups: Array.isArray(parsed.groups) ? parsed.groups : [],
+                };
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    this.snapshot = { users: [], groups: [] };
+                    return;
+                }
+                console.warn(`[scim] failed to load ${this.path}: ${err.message} — starting empty`);
+                this.snapshot = { users: [], groups: [] };
+            }
+        })();
+        return this.bootstrapped;
+    }
+    listUsers() {
+        return this.snapshot.users.slice();
+    }
+    getUser(id) {
+        return this.snapshot.users.find((u) => u.id === id);
+    }
+    getUserByUserName(userName) {
+        return this.snapshot.users.find((u) => u.userName === userName);
+    }
+    async createUser(input) {
+        if (!input.userName)
+            throw new ScimValidationError("userName is required");
+        if (this.getUserByUserName(input.userName)) {
+            throw new ScimValidationError(`User with userName '${input.userName}' already exists`, "uniqueness");
+        }
+        const ts = nowIso();
+        const user = {
+            schemas: [SCIM_SCHEMA_USER],
+            id: randomUUID(),
+            userName: input.userName,
+            active: input.active ?? true,
+            displayName: input.displayName,
+            name: input.name,
+            emails: input.emails,
+            externalId: input.externalId,
+            meta: { resourceType: "User", created: ts, lastModified: ts },
+        };
+        this.snapshot.users.push(user);
+        await this.persist();
+        return user;
+    }
+    async updateUser(id, patch) {
+        const i = this.snapshot.users.findIndex((u) => u.id === id);
+        if (i < 0)
+            throw new ScimNotFoundError(`User ${id} not found`);
+        const next = {
+            ...this.snapshot.users[i],
+            ...patch,
+            schemas: [SCIM_SCHEMA_USER],
+            id,
+            meta: {
+                ...this.snapshot.users[i].meta,
+                lastModified: nowIso(),
+            },
+        };
+        this.snapshot.users[i] = next;
+        await this.persist();
+        return next;
+    }
+    async deleteUser(id) {
+        const before = this.snapshot.users.length;
+        this.snapshot.users = this.snapshot.users.filter((u) => u.id !== id);
+        if (this.snapshot.users.length === before)
+            return false;
+        // Also remove the user from every group's members list.
+        for (const g of this.snapshot.groups) {
+            g.members = (g.members ?? []).filter((m) => m.value !== id);
+        }
+        await this.persist();
+        return true;
+    }
+    listGroups() {
+        return this.snapshot.groups.slice();
+    }
+    getGroup(id) {
+        return this.snapshot.groups.find((g) => g.id === id);
+    }
+    async createGroup(input) {
+        if (!input.displayName)
+            throw new ScimValidationError("displayName is required");
+        const ts = nowIso();
+        const group = {
+            schemas: [SCIM_SCHEMA_GROUP],
+            id: randomUUID(),
+            displayName: input.displayName,
+            members: input.members ?? [],
+            externalId: input.externalId,
+            meta: { resourceType: "Group", created: ts, lastModified: ts },
+        };
+        this.snapshot.groups.push(group);
+        await this.persist();
+        return group;
+    }
+    async updateGroup(id, patch) {
+        const i = this.snapshot.groups.findIndex((g) => g.id === id);
+        if (i < 0)
+            throw new ScimNotFoundError(`Group ${id} not found`);
+        const next = {
+            ...this.snapshot.groups[i],
+            ...patch,
+            schemas: [SCIM_SCHEMA_GROUP],
+            id,
+            meta: {
+                ...this.snapshot.groups[i].meta,
+                lastModified: nowIso(),
+            },
+        };
+        this.snapshot.groups[i] = next;
+        await this.persist();
+        return next;
+    }
+    async deleteGroup(id) {
+        const before = this.snapshot.groups.length;
+        this.snapshot.groups = this.snapshot.groups.filter((g) => g.id !== id);
+        if (this.snapshot.groups.length === before)
+            return false;
+        await this.persist();
+        return true;
+    }
+    /** Look up the groups a user is currently a member of — used to
+     *  populate `User.groups` on read responses. */
+    groupsContaining(userId) {
+        return this.snapshot.groups
+            .filter((g) => (g.members ?? []).some((m) => m.value === userId))
+            .map((g) => ({ value: g.id, display: g.displayName }));
+    }
+    async persist() {
+        await mkdir(dirname(this.path), { recursive: true }).catch(() => undefined);
+        const tmp = `${this.path}.tmp`;
+        await writeFile(tmp, JSON.stringify(this.snapshot, null, 2), { mode: 0o600 });
+        await rename(tmp, this.path);
+    }
+}
+export class ScimValidationError extends Error {
+    scimType;
+    constructor(message, scimType) {
+        super(message);
+        this.scimType = scimType;
+        this.name = "ScimValidationError";
+    }
+}
+export class ScimNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScimNotFoundError";
+    }
+}

package/dist/scim/store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scim/store.test.js

@@ -0,0 +1,121 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, statSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ScimStore, ScimValidationError, ScimNotFoundError } from "./store.js";
+function tmpStore() {
+    return join(mkdtempSync(join(tmpdir(), "scim-")), "scim.json");
+}
+test("ScimStore: load() on missing file → empty snapshot", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    assert.deepEqual(s.listUsers(), []);
+    assert.deepEqual(s.listGroups(), []);
+});
+test("ScimStore: createUser issues UUID id, sets schemas/meta, active=true default", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    assert.match(u.id, /^[0-9a-f-]{36}$/);
+    assert.deepEqual(u.schemas, ["urn:ietf:params:scim:schemas:core:2.0:User"]);
+    assert.equal(u.userName, "alice@example.com");
+    assert.equal(u.active, true);
+    assert.equal(u.meta.resourceType, "User");
+});
+test("ScimStore: createUser rejects duplicate userName with uniqueness scimType", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    await s.createUser({ userName: "alice@example.com" });
+    await assert.rejects(() => s.createUser({ userName: "alice@example.com" }), (e) => e instanceof ScimValidationError && e.scimType === "uniqueness");
+});
+test("ScimStore: createUser rejects missing userName", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    await assert.rejects(() => s.createUser({}), ScimValidationError);
+});
+test("ScimStore: getUser / getUserByUserName lookups", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    assert.equal(s.getUser(u.id)?.id, u.id);
+    assert.equal(s.getUserByUserName("alice@example.com")?.id, u.id);
+    assert.equal(s.getUser("nope"), undefined);
+});
+test("ScimStore: updateUser merges patch + bumps lastModified", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    const created = u.meta.lastModified;
+    await new Promise((r) => setTimeout(r, 5));
+    const updated = await s.updateUser(u.id, { displayName: "Alice" });
+    assert.equal(updated.displayName, "Alice");
+    assert.equal(updated.userName, "alice@example.com");
+    assert.notEqual(updated.meta.lastModified, created);
+});
+test("ScimStore: updateUser on missing id throws NotFound", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    await assert.rejects(() => s.updateUser("nope", { displayName: "x" }), ScimNotFoundError);
+});
+test("ScimStore: deleteUser removes user + scrubs them from group members", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    const g = await s.createGroup({
+        displayName: "admins",
+        members: [{ value: u.id, display: "Alice" }],
+    });
+    assert.equal(await s.deleteUser(u.id), true);
+    assert.equal(s.getUser(u.id), undefined);
+    const refreshed = s.getGroup(g.id);
+    assert.deepEqual(refreshed?.members, []);
+});
+test("ScimStore: deleteUser missing → false", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    assert.equal(await s.deleteUser("nope"), false);
+});
+test("ScimStore: createGroup with displayName + member list", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    const g = await s.createGroup({
+        displayName: "admins",
+        members: [{ value: u.id, display: "Alice" }],
+    });
+    assert.equal(g.displayName, "admins");
+    assert.equal(g.members?.length, 1);
+});
+test("ScimStore: groupsContaining(userId) returns the groups a user is in", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    await s.createGroup({ displayName: "admins", members: [{ value: u.id }] });
+    await s.createGroup({ displayName: "viewers", members: [{ value: u.id }] });
+    await s.createGroup({ displayName: "irrelevant", members: [] });
+    const got = s.groupsContaining(u.id);
+    assert.equal(got.length, 2);
+    assert.deepEqual(got.map((g) => g.display).sort(), ["admins", "viewers"]);
+});
+test("ScimStore: persists to disk with mode 0o600 (atomic tmp+rename)", async () => {
+    const path = tmpStore();
+    const s = new ScimStore(path);
+    await s.load();
+    await s.createUser({ userName: "alice@example.com" });
+    assert.ok(existsSync(path));
+    const mode = statSync(path).mode & 0o777;
+    assert.equal(mode, 0o600, `mode 0${mode.toString(8)} != 0600`);
+});
+test("ScimStore: round-trip through disk (load after persist sees the entries)", async () => {
+    const path = tmpStore();
+    const a = new ScimStore(path);
+    await a.load();
+    await a.createUser({ userName: "alice@example.com" });
+    await a.createGroup({ displayName: "admins", members: [{ value: a.listUsers()[0].id }] });
+    const b = new ScimStore(path);
+    await b.load();
+    assert.equal(b.listUsers().length, 1);
+    assert.equal(b.listGroups().length, 1);
+    assert.equal(b.listUsers()[0].userName, "alice@example.com");
+});

package/dist/scim/types.d.ts

@@ -0,0 +1,73 @@
+export declare const SCIM_SCHEMA_USER = "urn:ietf:params:scim:schemas:core:2.0:User";
+export declare const SCIM_SCHEMA_GROUP = "urn:ietf:params:scim:schemas:core:2.0:Group";
+export declare const SCIM_SCHEMA_PATCH_OP = "urn:ietf:params:scim:api:messages:2.0:PatchOp";
+export declare const SCIM_SCHEMA_LIST_RESPONSE = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+export declare const SCIM_SCHEMA_ERROR = "urn:ietf:params:scim:api:messages:2.0:Error";
+export interface ScimMeta {
+    resourceType: "User" | "Group";
+    created: string;
+    lastModified: string;
+    location?: string;
+    version?: string;
+}
+export interface ScimUser {
+    schemas: string[];
+    id: string;
+    userName: string;
+    active?: boolean;
+    displayName?: string;
+    name?: {
+        givenName?: string;
+        familyName?: string;
+        formatted?: string;
+    };
+    emails?: Array<{
+        value: string;
+        primary?: boolean;
+        type?: string;
+    }>;
+    /** SCIM `groups` is read-only — populated server-side from the
+     *  group→members linkage. */
+    groups?: Array<{
+        value: string;
+        display?: string;
+    }>;
+    externalId?: string;
+    meta: ScimMeta;
+}
+export interface ScimGroup {
+    schemas: string[];
+    id: string;
+    displayName: string;
+    members?: Array<{
+        value: string;
+        display?: string;
+        type?: "User" | "Group";
+    }>;
+    externalId?: string;
+    meta: ScimMeta;
+}
+export interface ScimListResponse<T> {
+    schemas: string[];
+    totalResults: number;
+    Resources: T[];
+    startIndex?: number;
+    itemsPerPage?: number;
+}
+export interface ScimError {
+    schemas: string[];
+    status: string;
+    scimType?: string;
+    detail?: string;
+}
+export interface ScimPatchOperation {
+    op: "add" | "remove" | "replace";
+    path?: string;
+    value?: unknown;
+}
+export interface ScimPatchRequest {
+    schemas: string[];
+    Operations: ScimPatchOperation[];
+}
+export declare function scimError(status: number, detail: string, scimType?: string): ScimError;
+export declare function nowIso(): string;

package/dist/scim/types.js

@@ -0,0 +1,29 @@
+// SCIM 2.0 — minimal shared types.
+//
+// The gateway implements the subset of SCIM 2.0 that the most-common
+// IdPs (Entra ID, Okta) use to provision Users and Groups. We do NOT
+// aim for full RFC 7643 / 7644 compliance — only the methods the
+// provisioning checklists exercise:
+//
+//   Users:   GET (list+by-id), POST, PATCH, DELETE
+//   Groups:  GET (list+by-id), POST, PATCH, DELETE
+//   Discovery: ServiceProviderConfig, ResourceTypes, Schemas
+//
+// Other operations (PUT/replace, Bulk, search-via-POST) are deferred
+// until an IdP customer explicitly requires them.
+export const SCIM_SCHEMA_USER = "urn:ietf:params:scim:schemas:core:2.0:User";
+export const SCIM_SCHEMA_GROUP = "urn:ietf:params:scim:schemas:core:2.0:Group";
+export const SCIM_SCHEMA_PATCH_OP = "urn:ietf:params:scim:api:messages:2.0:PatchOp";
+export const SCIM_SCHEMA_LIST_RESPONSE = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+export const SCIM_SCHEMA_ERROR = "urn:ietf:params:scim:api:messages:2.0:Error";
+export function scimError(status, detail, scimType) {
+    return {
+        schemas: [SCIM_SCHEMA_ERROR],
+        status: String(status),
+        scimType,
+        detail,
+    };
+}
+export function nowIso() {
+    return new Date().toISOString();
+}