@lpshanley/scim-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Shanley
+
+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/README.md

@@ -1,3 +1,194 @@
-# Temporary Holding Version
+# @lpshanley/scim-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A SCIM 2.0 service provider for Node.js servers built on `Request` and `Response`. An identity provider such as Okta or Microsoft Entra ID calls it to create, update and deactivate your users and groups.
+
+The package owns the protocol: validation, PATCH, filters, paging, discovery and SCIM responses. Your app owns tenants, tokens, storage, identity linking and what deprovisioning means.
+
+## Status
+
+This is an early release. It covers Users, Groups and discovery. It was extracted from a production app whose SCIM endpoint has received authentik pushes, and the package itself has handled live pushes from a disposable authentik 2026.8.5 and from an Okta trial org, using the catalog's SCIM 2.0 Test App, a classic App Integration Wizard app and an app built in the newer Okta Integration Wizard. That traffic is [kept in the repository](https://github.com/lpshanley/oidc-start/tree/main/packages/scim-core/recordings) and replayed in the tests. Failures were tested too: Okta's and authentik's reactions to 503 and 409 answers are recorded below. **No real Entra push has been tested**, so try it before relying on it.
+
+| Supported | Not supported yet |
+| --- | --- |
+| `/Users` and `/Groups`: create, read, list, PUT, PATCH, DELETE | Bulk operations and `/Me`, which answer 501 |
+| `/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas` | Sorting, ETags and `POST /.search`, which answers 405 |
+| Bearer tokens, resolved to a connection per request | Filters beyond `eq` clauses joined by `and` |
+| The core User and Group schemas, except `password` and `groups`, plus the enterprise extension | Custom schema extensions. Unknown attributes are accepted and not stored |
+| `attributes` and `excludedAttributes` on every resource response | Groups as group members |
+| Filters on `id`, `userName`, `externalId`, `displayName`, `emails.value` and `emails[type eq "x"].value` | |
+| Provider quirks: capitalized `op`, string booleans, no-path PATCH | |
+
+## Mount it
+
+The package needs Node.js 22.12 or newer.
+
+```ts
+import { createScim, createScimAdapter } from "@lpshanley/scim-core";
+
+const adapter = createScimAdapter({
+	read: (connection) => directoryStore(db, connection),
+	transaction: (connection, fn) => db.transaction((tx) => fn(directoryStore(tx, connection), tx)),
+});
+
+export const scim = createScim({
+	adapter,
+	authenticate: (token) => connections.findByTokenDigest(sha256(token)),
+	onUserDeprovisioned: (user, { tx }) => deleteMemberData(tx, user),
+	onChange: (change, { tx }) => audit(tx, change),
+	onCommitted: (change) => roles.clearCache(change),
+	onProblem: (problem) => log.warn("scim", problem.kind, problem.status),
+});
+```
+
+`scim.handle` takes a `Request` and returns a `Response`, so it works anywhere those exist. In TanStack Start, mount it at `src/routes/scim/v2/$.ts`:
+
+```ts
+import { createFileRoute } from "@tanstack/react-router";
+
+const handle = async ({ request }: { request: Request }) => {
+	const { scim } = await import("../../../scim.server");
+	return scim.handle(request);
+};
+
+export const Route = createFileRoute("/scim/v2/$")({
+	server: { handlers: { GET: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle } },
+});
+```
+
+Providers authenticate with a bearer token, so exempt this path from any browser CSRF check. If you mount somewhere else, set `basePath`. Behind a proxy that changes the host, set `origin` so resource locations stay correct.
+
+## Options
+
+| Option | Purpose |
+| --- | --- |
+| `adapter` | Your storage. See [Write an adapter](#write-an-adapter). |
+| `authenticate(token, request)` | Returns the connection for a token, or null to answer 401. Compare digests, and never store or log the token. |
+| `enabled()` | Answers 404 while false, for example until a token exists. |
+| `onUserDeprovisioned(user, context)` | Runs inside the transaction when a user is deactivated or deleted. If it throws, the change rolls back and the provider gets a 503 it can retry. What it returns reaches the change as `details`. |
+| `onChange(change, context)` | Runs inside the transaction for every change. Use it for audit rows. |
+| `onCommitted(change, context)` | Runs after commit. A failure here can't undo the change, and it is reported to `onProblem`. |
+| `onProblem(problem)` | Reports refused and failed requests. A refusal can leave a leaver with access, so alert on these. |
+| `externalId` | `"mutable"` (the default) or `"fixed"`. See [Behaviour worth knowing](#behaviour-worth-knowing). |
+| `basePath`, `origin`, `documentationUri` | Where the routes live and what discovery reports. |
+
+### Behaviour worth knowing
+
+- **Omitted fields on PUT:** a missing `active` or `externalId` keeps its current value, so a sparse update can't reactivate someone or break a link.
+- **`externalId` can change:** Entra sends a mail alias as `externalId` by default, and it changes when a person is renamed. The new value is stored, and the change carries `previousExternalId`, so relink there if your app links on it. Removing it is still refused.
+- **`externalId: "fixed"` refuses that change:** choose it when your app treats `externalId` as the link to a sign-in identity. A change then answers `400 mutability`, which is stricter than RFC 7643 and fails the whole request, including a rename sent with it. A deactivation still goes through and keeps the stored value, and the change carries `externalIdConflict`.
+- **Reactivation is its own change:** an inactive user made active again reports `user.reactivated`, not `user.updated`, so you can restore what `onUserDeprovisioned` ended.
+- **Storage failures answer 503, never 404:** a 404 would tell the provider the user is gone. Okta shows its admin the package's own `detail` text, and then does not retry. See [When a request fails](#when-a-request-fails).
+- **Unknown attributes are accepted and dropped:** refusing one would fail the whole request, which might also be a deactivation. This includes unknown sub-attributes inside a list entry or `manager`. `/Schemas` lists what is kept.
+- **`null` means unassigned:** on POST and PUT, a null value is treated as omitted. A null `userName` is still refused.
+- **No `meta.version`:** ETags aren't supported, so responses don't claim a version. Your store still tracks one for your own use.
+- **A typed value is created when missing:** a `replace` of `emails[type eq "work"].value` adds the address if there is none, where RFC 7644 asks for `noTarget`. Other unmatched value paths do answer `noTarget`.
+- **PATCH paths are checked:** a malformed path answers `invalidPath`, and a path naming `id`, `meta`, `groups` or `schemas` answers `mutability`. A no-path PATCH ignores those keys, because Okta sends the group's `id` when renaming it.
+- **A value filter beyond `type` or `value` is dropped:** a path such as `emails[type eq "work" and primary eq true].value` is valid, not applied, and answers 200 like an unknown attribute.
+- **Two spellings of one attribute:** if a body has both `active` and `Active`, the canonical spelling wins.
+- **A missing `schemas` is accepted:** on any request, which is more lenient than the RFC.
+- **A change that changes nothing is skipped:** a PATCH or PUT that leaves the resource as it was keeps its `lastModified`, and no hook runs. Okta's wizard apps send such PUTs for groups.
+
+## Use it without HTTP
+
+`forConnection` gives application code the same operations, with the same transaction and hooks as a provider's request:
+
+```ts
+await scim.forConnection(connection).users.deactivate(id);
+```
+
+## Write an adapter
+
+A connection is whatever `authenticate` returns, usually one customer's directory. Implement [`ScimStore`](https://github.com/lpshanley/oidc-start/blob/main/packages/scim-core/src/adapter.ts) for one connection, and return it from `read` and from `transaction`. Stores must only see that connection's rows.
+
+A user has first-class `emails`, and `attributes` holds the rest of the schema, such as `title`, `phoneNumbers` and the enterprise extension under its URN. Store `attributes` as JSON and return it unchanged. `store.users` must also filter on `id`, `email` and `emailType`, and `testScimAdapter` checks this.
+
+To give hooks your own user fields, such as a linked OIDC subject, return them from the store and pass your type to `createScimAdapter<Connection, MyUser, MyTransaction>`.
+
+## Test it
+
+`@lpshanley/scim-core/testing` has these tools:
+
+```ts
+import { createMemoryAdapter, createTestProvider, testScimAdapter } from "@lpshanley/scim-core/testing";
+import { expect, test } from "vitest";
+
+// Does my adapter honour the contract? Run this against your real database.
+testScimAdapter({
+	setup: async () => ({ adapter: await emptyAdapter(), connections: ["acme", "globex"] }),
+	test,
+});
+
+// Does my app behave when a provider's requests arrive?
+test("a leaver loses access", async () => {
+	const idp = createTestProvider(scim, { dialect: "entra", token });
+	const user = await idp.createUser({ userName: "a@x.test" });
+	await idp.deactivate(user);
+	expect(await sessions.forUser(user)).toEqual([]);
+});
+```
+
+`createMemoryAdapter()` is a single-process adapter for trying the package and for fast tests. The `okta`, `okta-wizard`, `entra` and `authentik` dialects are modelled on vendor documentation and that app's records, not captured traffic, so they show your app handles those shapes, not that a real push works. The repository's [`recordings/`](https://github.com/lpshanley/oidc-start/tree/main/packages/scim-core/recordings) folder holds captured traffic from authentik and from three Okta app types. All three Okta apps update a profile with a GET and a PUT. The test app and the newer wizard app deactivate and reactivate with a no-path PATCH and change groups with PATCH, and the classic wizard app uses PUT for all of those. `okta` is an OIN integration, and `okta-wizard` is an App Integration Wizard app, which updates with PUT.
+
+### When a request fails
+
+Okta's behaviour, observed against writes that failed ([`recordings/okta-failures-2026-11.jsonl`](https://github.com/lpshanley/oidc-start/blob/main/packages/scim-core/recordings/okta-failures-2026-11.jsonl)):
+
+- **It does not retry.** A create that answered 503 stayed failed for eight minutes, including after the server recovered. The admin has to select the assignment on the Tasks page and press **Retry Selected**, which repeats the lookup and the create.
+- **It shows your `detail` text** in the assignment's error, so keep those messages free of anything private.
+- **A 409 on create is a plain failure.** Okta does not look the user up again or link them.
+- **A failed deactivation becomes a manual task.** Okta creates "Application accounts need deprovisioning" for the admin and sent no retry in the three minutes we watched. Until someone acts, the person is still active in your app. A deactivation sent by unassigning someone and one sent by deactivating them in Okta are the same `PATCH`.
+
+So alert on `onProblem` with `kind: "failed"` for a `PATCH`, `PUT` or `DELETE`. Okta will not try again, and it only raises a task in its own console.
+
+To reproduce a failure against a real provider, the harness can fail writes on demand: write `{"mode":"unavailable","times":2}` (or `"conflict"`) to `harness/fault.json` in the repository's [harness](https://github.com/lpshanley/oidc-start/blob/main/packages/scim-core/harness/server.mjs) while it runs.
+
+### authentik
+
+Observed against authentik 2026.8.5 ([`recordings/authentik-2026.8.5.jsonl`](https://github.com/lpshanley/oidc-start/blob/main/packages/scim-core/recordings/authentik-2026.8.5.jsonl) and [`recordings/authentik-failures-2026.8.5.jsonl`](https://github.com/lpshanley/oidc-start/blob/main/packages/scim-core/recordings/authentik-failures-2026.8.5.jsonl)):
+
+- **It retries failed writes by itself.** A user update that answered 503 was retried through authentik's job queue with growing delays, about one and a half, four and five minutes, and applied about a minute after the server recovered, ten minutes after the first failure. That is the opposite of Okta, so a short outage heals without anyone acting. How long it keeps trying is not known.
+- **A 409 on create makes it look the user up by `userName`,** then link to the match, or create again if there is none. A user that already existed is linked and not changed at first. Its next update, and every update in a full sync, then sends authentik's own `externalId`. By default the package stores it. With `externalId: "fixed"` each of those updates answers `400 mutability`, so a pre-existing user whose `externalId` differs stays stuck. Don't pre-create people with a different `externalId` if you choose `"fixed"`.
+- **Attributes outside the kept set are dropped.** A custom property mapping sent `costCenter` and a custom schema URN, and the package answered 200 and stored neither. `title`, `phoneNumbers` and the enterprise extension were kept.
+- **All seven compatibility modes work:** default, aws, slack, sfdc, gitlab, webex and vcenter. AWS, Salesforce, GitLab and vCenter change groups with `PUT` where the others use `PATCH`, and Webex adds `"type": "user"` to members. Salesforce mode asks for `/ServiceProviderConfigs`, which answers 404 and does no harm.
+- **The default full sync runs every four hours** (`49 */4 * * *`), not every hour. It sends a `PUT` for every user, and the package skips the ones that changed nothing.
+- **Volume:** 300 new users synced in under two minutes, listing paged correctly at 100 a time, and a full sync of 305 users finished in under a minute with no errors. Authentik itself left two of the 300 unpushed until the next full sync, with no error in either system, so a user can be missing for up to four hours.
+
+### Capture real traffic
+
+`recordTraffic` wraps an instance and reports each exchange. Headers are never kept, passwords are dropped, and names, emails and filter values become placeholders. `replayTraffic` sends a recording to a fresh instance and returns any exchange whose status changed, so a provider's real requests can become a regression test:
+
+```ts
+const recording = readFileSync("okta.jsonl", "utf8").trim().split("\n").map((line) => JSON.parse(line));
+expect(await replayTraffic(scim, recording, { token })).toEqual([]);
+```
+
+Read a recording before you commit it, because an attribute the scrubber doesn't know about keeps its value.
+
+In the repository, [`harness/server.mjs`](https://github.com/lpshanley/oidc-start/blob/main/packages/scim-core/harness/server.mjs) is a throwaway server for this. It keeps users in memory, and it listens on localhost, so a provider needs an HTTPS tunnel to reach it:
+
+```bash
+pnpm --filter @lpshanley/scim-core build
+cd packages/scim-core
+SCIM_HARNESS_TOKEN="$(openssl rand -hex 32)" node harness/server.mjs
+```
+
+## Use it with oidc-start
+
+The two packages don't depend on each other, and SCIM users aren't `AuthUser`s: someone can be provisioned before they ever sign in. Linking them is a choice your app makes:
+
+- **Link deliberately.** A SCIM `id` or `externalId` is not automatically an OIDC `(issuer, sub)`. Only treat `externalId` as `sub` if your provider's configuration guarantees it, and then set `externalId: "fixed"`. Linking by email at first sign-in needs a verified email claim from a trusted issuer.
+- **Refuse deprovisioned users.** Check your directory in `allowSession`.
+- **End current sessions.** Call `SessionRegistry.endAll` once the change commits:
+
+```ts
+const scim = createScim({
+	// ...
+	onCommitted: async (change, { connection }) => {
+		if (change.type !== "user.deactivated" && change.type !== "user.deleted") return;
+		if (change.user.subject)
+			await registry.endAll({ issuer: connection.issuer, clientId: connection.clientId, sub: change.user.subject });
+	},
+});
+```
+
+If `endAll` fails, the change has already committed, and `onProblem` hears about it as `after-commit`. `allowSession` covers that gap, because oidc-start checks it whenever it resolves a session, not only at sign-in. The directory check there must fail closed.

package/dist/adapter.d.ts

@@ -0,0 +1,45 @@
+import type { ScimGroup, ScimGroupFields, ScimGroupFilter, ScimPage, ScimUser, ScimUserFields, ScimUserFilter } from "./types.js";
+/**
+ * Storage for one connection. Inside a transaction, `user` and `group` should
+ * lock the row, because a write is based on what they return.
+ *
+ * Absent resources come back as undefined or false. A write that would
+ * duplicate a live userName, externalId or group name throws ScimConflictError,
+ * and member changes naming an unknown user throw ScimError 400 invalidValue.
+ * Adding a member twice and removing an absent member are no-ops.
+ */
+export interface ScimStore<TUser extends ScimUser = ScimUser> {
+    user(id: string): Promise<TUser | undefined>;
+    /**
+     * Every given key must match. `userName`, `email` and `emailType` match
+     * case-insensitively, and `emailType` applies to the same address as `email`.
+     * Order must be stable across pages.
+     */
+    users(filter: ScimUserFilter, offset: number, limit: number): Promise<ScimPage<TUser>>;
+    createUser(fields: ScimUserFields): Promise<TUser>;
+    replaceUser(id: string, fields: ScimUserFields): Promise<TUser | undefined>;
+    /** Also removes the user from every group. */
+    deleteUser(id: string): Promise<TUser | undefined>;
+    group(id: string): Promise<ScimGroup | undefined>;
+    /** `displayName` matches case-insensitively, as it does for uniqueness. */
+    groups(filter: ScimGroupFilter, offset: number, limit: number): Promise<ScimPage<ScimGroup>>;
+    createGroup(fields: ScimGroupFields): Promise<string>;
+    /** An undefined externalId keeps the current value. */
+    renameGroup(id: string, displayName: string, externalId?: string | null): Promise<boolean>;
+    setMembers(groupId: string, userIds: string[]): Promise<void>;
+    addMembers(groupId: string, userIds: string[]): Promise<void>;
+    removeMembers(groupId: string, userIds: string[]): Promise<void>;
+    deleteGroup(id: string): Promise<boolean>;
+}
+/**
+ * How the package reaches the host's storage. A connection is whatever the
+ * host's `authenticate` returns, usually one customer's directory. Stores must
+ * only see that connection's rows. `TTransaction` is the host's handle, passed
+ * to hooks so their writes commit or roll back with the change.
+ */
+export interface ScimAdapter<TConnection, TUser extends ScimUser = ScimUser, TTransaction = undefined> {
+    read(connection: TConnection): ScimStore<TUser>;
+    transaction<T>(connection: TConnection, fn: (store: ScimStore<TUser>, tx: TTransaction) => Promise<T>): Promise<T>;
+}
+/** Declares an adapter and infers its types for `createScim`. */
+export declare function createScimAdapter<TConnection, TUser extends ScimUser = ScimUser, TTransaction = undefined>(adapter: ScimAdapter<TConnection, TUser, TTransaction>): ScimAdapter<TConnection, TUser, TTransaction>;

package/dist/adapter.js

@@ -0,0 +1,4 @@
+/** Declares an adapter and infers its types for `createScim`. */
+export function createScimAdapter(adapter) {
+    return adapter;
+}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/** A SCIM protocol error (RFC 7644 §3.12). */
+export declare class ScimError extends Error {
+    readonly status: number;
+    readonly scimType?: string;
+    constructor(status: number, scimType?: string, detail?: string);
+    body(): {
+        detail: string;
+        scimType?: string | undefined;
+        schemas: string[];
+        status: string;
+    };
+}
+/** Thrown by an adapter when a write would duplicate a unique value. Answers 409. */
+export declare class ScimConflictError extends ScimError {
+    constructor(detail?: string);
+}
+export declare const notFound: () => ScimError;

package/dist/errors.js

@@ -0,0 +1,28 @@
+const ERROR = "urn:ietf:params:scim:api:messages:2.0:Error";
+/** A SCIM protocol error (RFC 7644 §3.12). */
+export class ScimError extends Error {
+    status;
+    scimType;
+    constructor(status, scimType, detail = "") {
+        super(detail || scimType || String(status));
+        this.name = "ScimError";
+        this.status = status;
+        this.scimType = scimType;
+    }
+    body() {
+        return {
+            schemas: [ERROR],
+            status: String(this.status),
+            ...(this.scimType ? { scimType: this.scimType } : {}),
+            detail: this.message,
+        };
+    }
+}
+/** Thrown by an adapter when a write would duplicate a unique value. Answers 409. */
+export class ScimConflictError extends ScimError {
+    constructor(detail = "Already exists") {
+        super(409, "uniqueness", detail);
+        this.name = "ScimConflictError";
+    }
+}
+export const notFound = () => new ScimError(404, undefined, "Resource not found");

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createScim, type ScimOptions, type ScimProblem } from "./scim.js";
+export { createScimAdapter, type ScimAdapter, type ScimStore } from "./adapter.js";
+export { ScimConflictError, ScimError } from "./errors.js";
+export type { ScimChange, ScimHooks } from "./operations.js";
+export type { ScimAttributes, ScimEmail, ScimGroup, ScimGroupChange, ScimGroupFields, ScimGroupFilter, ScimName, ScimPage, ScimUser, ScimUserFields, ScimUserFilter, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createScim } from "./scim.js";
+export { createScimAdapter } from "./adapter.js";
+export { ScimConflictError, ScimError } from "./errors.js";

package/dist/operations.d.ts

@@ -0,0 +1,104 @@
+import type { ScimAdapter } from "./adapter.js";
+import type { ScimGroup, ScimGroupChange, ScimGroupFields, ScimGroupFilter, ScimUser, ScimUserFilter } from "./types.js";
+type Details = Record<string, unknown>;
+type GroupSummary = {
+    id: string;
+    displayName: string;
+};
+/** Present when the stored externalId changed, with the value it replaced. Relink on this if you link by externalId. */
+type ExternalIdChange = {
+    previousExternalId?: string | null;
+};
+/** What a committed request changed. */
+export type ScimChange<TUser extends ScimUser = ScimUser> = {
+    type: "user.created";
+    user: TUser;
+} | ({
+    type: "user.updated";
+    user: TUser;
+} & ExternalIdChange)
+/** An inactive user became active again, so access ended at deactivation can be restored. */
+ | ({
+    type: "user.reactivated";
+    user: TUser;
+} & ExternalIdChange)
+/** `externalIdConflict`: with a fixed externalId, the request sent a different one, which was not stored. */
+ | ({
+    type: "user.deactivated";
+    user: TUser;
+    details?: Details;
+    externalIdConflict?: true;
+} & ExternalIdChange) | {
+    type: "user.deleted";
+    user: TUser;
+    details?: Details;
+} | {
+    type: "group.created";
+    group: GroupSummary;
+    members: number;
+} | {
+    type: "group.replaced";
+    group: GroupSummary;
+    members: number;
+} | {
+    type: "group.patched";
+    group: GroupSummary;
+    added: number;
+    removed: number;
+    replaced: boolean;
+} | {
+    type: "group.deleted";
+    group: GroupSummary;
+};
+export type ScimHooks<TConnection, TUser extends ScimUser, TTransaction> = {
+    /**
+     * Runs inside the transaction when a user is deactivated or deleted, so a
+     * failure rolls the change back. End access and delete the user's data
+     * here. What it returns reaches `onChange` and `onCommitted` as `details`.
+     */
+    onUserDeprovisioned?(user: TUser, context: {
+        connection: TConnection;
+        tx: TTransaction;
+        reason: "deactivated" | "deleted";
+    }): Promise<Details | void>;
+    /** Runs inside the transaction for every change, for example to write an audit row. */
+    onChange?(change: ScimChange<TUser>, context: {
+        connection: TConnection;
+        tx: TTransaction;
+    }): Promise<void>;
+    /** Runs after commit, for example to clear a cache. A failure here cannot undo the change. */
+    onCommitted?(change: ScimChange<TUser>, context: {
+        connection: TConnection;
+    }): Promise<void> | void;
+};
+type Options<TConnection, TUser extends ScimUser, TTransaction> = ScimHooks<TConnection, TUser, TTransaction> & {
+    adapter: ScimAdapter<TConnection, TUser, TTransaction>;
+    externalId?: "mutable" | "fixed";
+    /** Reports a hook that failed after commit. */
+    afterCommitFailed(error: unknown): void;
+};
+/**
+ * Every change runs in one transaction with its hooks. HTTP requests and direct
+ * calls share this path, so both end access the same way.
+ */
+export declare function createOperations<TConnection, TUser extends ScimUser, TTransaction>(options: Options<TConnection, TUser, TTransaction>, connection: TConnection): {
+    users: {
+        get: (id: string) => Promise<TUser>;
+        list: (filter: ScimUserFilter, offset: number, limit: number) => Promise<import("./types.js").ScimPage<TUser>>;
+        create: (body: unknown) => Promise<TUser>;
+        replace: (id: string, body: unknown) => Promise<TUser>;
+        patch: (id: string, body: unknown) => Promise<TUser>;
+        /** An offboarding the application started. It takes the same path as a provider's request. */
+        deactivate: (id: string) => Promise<TUser>;
+        delete: (id: string) => Promise<void>;
+    };
+    groups: {
+        get: (id: string) => Promise<ScimGroup>;
+        list: (filter: ScimGroupFilter, offset: number, limit: number) => Promise<import("./types.js").ScimPage<ScimGroup>>;
+        create: (fields: ScimGroupFields) => Promise<ScimGroup>;
+        replace: (id: string, fields: ScimGroupFields) => Promise<ScimGroup>;
+        patch: (id: string, patch: ScimGroupChange[]) => Promise<ScimGroup>;
+        delete: (id: string) => Promise<void>;
+    };
+};
+export {};

package/dist/operations.js

@@ -0,0 +1,204 @@
+import { isDeepStrictEqual } from "node:util";
+import { notFound, ScimError } from "./errors.js";
+import { patchUser, parseUser, replaceUser } from "./protocol.js";
+const fieldsOf = ({ userName, externalId, displayName, name, emails, attributes, active }) => ({
+    userName,
+    externalId,
+    displayName,
+    name,
+    emails,
+    attributes,
+    active,
+});
+const summary = (g) => ({ id: g.id, displayName: g.displayName });
+/** Whether a group PATCH would leave the group as it is. */
+function unchanged(group, patch) {
+    const before = group.members.map((m) => m.id);
+    const members = new Set(before);
+    let { displayName, externalId } = group;
+    for (const change of patch) {
+        if (change.kind === "rename")
+            displayName = change.displayName;
+        else if (change.kind === "externalId")
+            externalId = change.externalId;
+        else if (change.kind === "add")
+            for (const id of change.ids)
+                members.add(id);
+        else if (change.kind === "remove")
+            for (const id of change.ids)
+                members.delete(id);
+        else {
+            members.clear();
+            for (const id of change.ids)
+                members.add(id);
+        }
+    }
+    return (displayName === group.displayName &&
+        externalId === group.externalId &&
+        members.size === before.length &&
+        before.every((id) => members.has(id)));
+}
+/**
+ * Every change runs in one transaction with its hooks. HTTP requests and direct
+ * calls share this path, so both end access the same way.
+ */
+export function createOperations(options, connection) {
+    const { adapter, onUserDeprovisioned, onChange, onCommitted } = options;
+    async function commit(fn) {
+        const changes = [];
+        const result = await adapter.transaction(connection, (store, tx) => fn(store, tx, async (change) => {
+            await onChange?.(change, { connection, tx });
+            changes.push(change);
+        }));
+        for (const change of changes) {
+            try {
+                await onCommitted?.(change, { connection });
+            }
+            catch (error) {
+                options.afterCommitFailed(error);
+            }
+        }
+        return result;
+    }
+    const deprovision = async (user, tx, reason) => (await onUserDeprovisioned?.(user, { connection, tx, reason })) ?? undefined;
+    const write = (id, next) => commit(async (store, tx, record) => {
+        const current = await store.user(id);
+        if (!current)
+            throw notFound();
+        const fields = next(fieldsOf(current));
+        const conflict = options.externalId === "fixed" && current.externalId !== null && fields.externalId !== current.externalId;
+        const deactivating = current.active && !fields.active;
+        const reactivating = !current.active && fields.active;
+        // Ending access matters more than a clean request, so a deactivation
+        // still goes through and the stored externalId stays as it was.
+        if (conflict && !deactivating)
+            throw new ScimError(400, "mutability", "externalId cannot change");
+        const stored = conflict ? { ...fields, externalId: current.externalId } : fields;
+        // An unchanged resource keeps its lastModified (RFC 7644 §3.5.2.1).
+        if (isDeepStrictEqual(stored, fieldsOf(current)))
+            return current;
+        const user = await store.replaceUser(id, stored);
+        if (!user)
+            throw notFound();
+        const relinked = stored.externalId === current.externalId ? {} : { previousExternalId: current.externalId };
+        if (deactivating) {
+            const details = await deprovision(user, tx, "deactivated");
+            await record({
+                type: "user.deactivated",
+                user,
+                ...(details ? { details } : {}),
+                ...(conflict ? { externalIdConflict: true } : {}),
+                ...relinked,
+            });
+        }
+        else
+            await record({ type: reactivating ? "user.reactivated" : "user.updated", user, ...relinked });
+        return user;
+    });
+    const group = async (id) => (await adapter.read(connection).group(id)) ?? Promise.reject(notFound());
+    return {
+        users: {
+            get: async (id) => (await adapter.read(connection).user(id)) ?? Promise.reject(notFound()),
+            list: (filter, offset, limit) => adapter.read(connection).users(filter, offset, limit),
+            create: (body) => {
+                const fields = parseUser(body);
+                return commit(async (store, _tx, record) => {
+                    const user = await store.createUser(fields);
+                    await record({ type: "user.created", user });
+                    return user;
+                });
+            },
+            replace: (id, body) => write(id, (current) => replaceUser(current, body)),
+            patch: (id, body) => write(id, (current) => patchUser(current, body)),
+            /** An offboarding the application started. It takes the same path as a provider's request. */
+            deactivate: (id) => write(id, (current) => ({ ...current, active: false })),
+            delete: (id) => commit(async (store, tx, record) => {
+                const user = await store.deleteUser(id);
+                if (!user)
+                    throw notFound();
+                const details = await deprovision(user, tx, "deleted");
+                await record({ type: "user.deleted", user, ...(details ? { details } : {}) });
+            }),
+        },
+        groups: {
+            get: group,
+            list: (filter, offset, limit) => adapter.read(connection).groups(filter, offset, limit),
+            create: async (fields) => {
+                const id = await commit(async (store, _tx, record) => {
+                    const id = await store.createGroup(fields);
+                    await record({
+                        type: "group.created",
+                        group: { id, displayName: fields.displayName },
+                        members: fields.memberIds.length,
+                    });
+                    return id;
+                });
+                return group(id);
+            },
+            replace: async (id, fields) => {
+                await commit(async (store, _tx, record) => {
+                    const current = await store.group(id);
+                    if (!current)
+                        throw notFound();
+                    // Okta's wizard apps send a PUT that repeats the group as it is. Like a
+                    // no-op PATCH, it keeps lastModified and runs no hook.
+                    const same = unchanged(current, [
+                        { kind: "rename", displayName: fields.displayName },
+                        { kind: "externalId", externalId: fields.externalId ?? current.externalId },
+                        { kind: "replace", ids: fields.memberIds },
+                    ]);
+                    if (same)
+                        return;
+                    await store.renameGroup(id, fields.displayName, fields.externalId ?? current.externalId);
+                    await store.setMembers(id, fields.memberIds);
+                    await record({
+                        type: "group.replaced",
+                        group: { id, displayName: fields.displayName },
+                        members: fields.memberIds.length,
+                    });
+                });
+                return group(id);
+            },
+            patch: async (id, patch) => {
+                await commit(async (store, _tx, record) => {
+                    const current = await store.group(id);
+                    if (!current)
+                        throw notFound();
+                    if (unchanged(current, patch))
+                        return;
+                    let displayName = current.displayName;
+                    const counts = { added: 0, removed: 0, replaced: false };
+                    for (const change of patch) {
+                        if (change.kind === "rename") {
+                            displayName = change.displayName;
+                            await store.renameGroup(id, displayName);
+                        }
+                        else if (change.kind === "externalId") {
+                            await store.renameGroup(id, displayName, change.externalId);
+                        }
+                        else if (change.kind === "add") {
+                            counts.added += change.ids.length;
+                            await store.addMembers(id, change.ids);
+                        }
+                        else if (change.kind === "remove") {
+                            counts.removed += change.ids.length;
+                            await store.removeMembers(id, change.ids);
+                        }
+                        else {
+                            counts.replaced = true;
+                            await store.setMembers(id, change.ids);
+                        }
+                    }
+                    await record({ type: "group.patched", group: { id, displayName }, ...counts });
+                });
+                return group(id);
+            },
+            delete: (id) => commit(async (store, _tx, record) => {
+                const current = await store.group(id);
+                if (!current || !(await store.deleteGroup(id)))
+                    throw notFound();
+                await record({ type: "group.deleted", group: summary(current) });
+            }),
+        },
+    };
+}