@maroonedsoftware/scim 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marooned Software
+
+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

@@ -0,0 +1,62 @@
+# @maroonedsoftware/scim
+
+SCIM 2.0 (RFC 7643/7644) server toolkit for ServerKit.
+
+This package provides the protocol layer — schemas, filter parser, PATCH applier, error envelope, and a Koa router — for building a SCIM server. Resource storage is left to the consumer via abstract repositories, matching the pattern used by `@maroonedsoftware/authentication` and `@maroonedsoftware/permissions`.
+
+## What's included
+
+- **Resource schemas** — `User`, `Group`, and the `EnterpriseUser` extension (RFC 7643).
+- **Filter parser** — full SCIM filter grammar (RFC 7644 §3.4.2.2) returning a typed AST.
+- **PATCH applier** — `add` / `replace` / `remove` ops with the path mini-language (RFC 7644 §3.5.2).
+- **Error envelope** — `scimError(status, scimType?)` builder producing the SCIM error JSON.
+- **Abstract repositories** — `ScimUserRepository`, `ScimGroupRepository`. The consumer implements these against their datastore.
+- **Services** — `ScimUserService`, `ScimGroupService`, `ScimServiceProviderService`.
+- **Koa middleware** — `scimErrorMiddleware()`, `scimContentTypeMiddleware()`, `requireScimScope(scope)`.
+- **Router factory** — `createScimRouter(options)` mounting the standard SCIM endpoints.
+
+## Quick start
+
+```ts
+import Koa from 'koa';
+import { ServerKitContext, serverKitContextMiddleware, authenticationMiddleware } from '@maroonedsoftware/koa';
+import { createScimRouter, ScimUserRepository, ScimGroupRepository, scimErrorMiddleware } from '@maroonedsoftware/scim';
+
+class MyScimUserRepository extends ScimUserRepository {
+  // implement against your datastore
+}
+
+class MyScimGroupRepository extends ScimGroupRepository {
+  // implement against your datastore
+}
+
+const app = new Koa();
+app.use(serverKitContextMiddleware(container));
+app.use(authenticationMiddleware());
+
+const scimRouter = createScimRouter({
+  userRepository: new MyScimUserRepository(),
+  groupRepository: new MyScimGroupRepository(),
+  basePath: '/scim/v2',
+  serviceProviderConfig: {
+    documentationUri: 'https://example.com/scim/docs',
+    patch: { supported: true },
+    bulk: { supported: false, maxOperations: 0, maxPayloadSize: 0 },
+    filter: { supported: true, maxResults: 200 },
+    changePassword: { supported: false },
+    sort: { supported: true },
+    etag: { supported: false },
+  },
+});
+
+app.use(scimErrorMiddleware());
+app.use(scimRouter.routes());
+```
+
+## Authentication
+
+This package does not validate bearer tokens itself. It reads `ctx.authenticationSession` (populated by `authenticationMiddleware()` from `@maroonedsoftware/koa`) and provides a `requireScimScope(scope)` guard that checks for SCIM scopes on `session.claims.scimScopes`. You register an `AuthenticationSchemeHandler` in your app that turns IdP-issued bearer tokens into a session.
+
+## Compliance testing
+
+The router has been designed against RFC 7643/7644. To validate against a real IdP, point Okta or [`scim2-compliance-test-utils`](https://github.com/suvera/scim2-compliance-test-utils) at a sample app that mounts `createScimRouter`.

package/dist/errors/scim.error.d.ts

@@ -0,0 +1,42 @@
+import { HttpError, HttpStatusCodes, type HttpStatusMessage } from '@maroonedsoftware/errors';
+/** Schema URI for the SCIM Error message. */
+export declare const ScimErrorSchema = "urn:ietf:params:scim:api:messages:2.0:Error";
+/**
+ * `scimType` values defined by RFC 7644 §3.12 plus the few extensions clients
+ * commonly emit. Keep this open as `string` to allow vendor-specific values.
+ */
+export type ScimErrorType = 'invalidFilter' | 'tooMany' | 'uniqueness' | 'mutability' | 'invalidSyntax' | 'invalidPath' | 'noTarget' | 'invalidValue' | 'invalidVers' | 'sensitive' | 'insufficientScope' | (string & {});
+/**
+ * SCIM error envelope (RFC 7644 §3.12). The HTTP status comes from
+ * the underlying {@link HttpError}; the JSON body matches:
+ *
+ * ```json
+ * { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "404", "scimType": "invalidPath", "detail": "..." }
+ * ```
+ */
+export declare class ScimError extends HttpError {
+    /** SCIM-specific error subtype, see RFC 7644 §3.12. */
+    readonly scimType?: ScimErrorType;
+    constructor(statusCode: HttpStatusCodes, scimType?: ScimErrorType, message?: HttpStatusMessage<HttpStatusCodes>);
+    /** Build the SCIM error JSON body for this error. */
+    toScimBody(): {
+        schemas: [typeof ScimErrorSchema];
+        status: string;
+        scimType?: ScimErrorType;
+        detail?: string;
+    };
+}
+/** Type guard for {@link ScimError}. */
+export declare const IsScimError: (error: unknown) => error is ScimError;
+/**
+ * Factory for building a SCIM-shaped HTTP error. The returned object behaves like
+ * an {@link HttpError}, so chained `.withDetails()` / `.withCause()` /
+ * `.withInternalDetails()` work as usual.
+ *
+ * @example
+ * ```ts
+ * throw scimError(400, 'invalidFilter', 'Bad Request');
+ * ```
+ */
+export declare const scimError: <Status extends HttpStatusCodes>(statusCode: Status, scimType?: ScimErrorType, message?: HttpStatusMessage<Status>) => ScimError;
+//# sourceMappingURL=scim.error.d.ts.map

package/dist/errors/scim.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scim.error.d.ts","sourceRoot":"","sources":["../../src/errors/scim.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE9F,6CAA6C;AAC7C,eAAO,MAAM,eAAe,gDAAgD,CAAC;AAE7E;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,SAAS,GACT,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,aAAa,GACb,UAAU,GACV,cAAc,GACd,aAAa,GACb,WAAW,GACX,mBAAmB,GACnB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,SAAS;IACtC,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;gBAEtB,UAAU,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,eAAe,CAAC;IAM/G,qDAAqD;IACrD,UAAU,IAAI;QAAE,OAAO,EAAE,CAAC,OAAO,eAAe,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAQ/G;AAED,wCAAwC;AACxC,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,SAAuC,CAAC;AAE9F;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,SAAS,eAAe,EACtD,YAAY,MAAM,EAClB,WAAW,aAAa,EACxB,UAAU,iBAAiB,CAAC,MAAM,CAAC,KAClC,SAAyD,CAAC"}

package/dist/filter/filter.ast.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SCIM filter comparison operators (RFC 7644 §3.4.2.2).
+ */
+export type ScimComparisonOperator = 'eq' | 'ne' | 'co' | 'sw' | 'ew' | 'gt' | 'ge' | 'lt' | 'le' | 'pr';
+/**
+ * SCIM filter logical operators.
+ */
+export type ScimLogicalOperator = 'and' | 'or';
+/**
+ * Comparison node: `<attrPath> <op> <value>` or `<attrPath> pr` (presence).
+ */
+export interface ScimFilterComparison {
+    kind: 'comparison';
+    /** Attribute path, e.g. `userName`, `name.familyName`, `urn:.../User:userName`. */
+    attribute: string;
+    operator: ScimComparisonOperator;
+    /** Literal value; absent for `pr` (presence). */
+    value?: string | number | boolean | null;
+}
+/** Boolean conjunction / disjunction. */
+export interface ScimFilterLogical {
+    kind: 'logical';
+    operator: ScimLogicalOperator;
+    left: ScimFilterNode;
+    right: ScimFilterNode;
+}
+/** Negation: `not(<filter>)`. */
+export interface ScimFilterNot {
+    kind: 'not';
+    filter: ScimFilterNode;
+}
+/** Value-path filter: `emails[type eq "work" and primary eq true]`. */
+export interface ScimFilterValuePath {
+    kind: 'valuePath';
+    attribute: string;
+    filter: ScimFilterNode;
+}
+/** Discriminated union of every parsed SCIM filter node. */
+export type ScimFilterNode = ScimFilterComparison | ScimFilterLogical | ScimFilterNot | ScimFilterValuePath;
+//# sourceMappingURL=filter.ast.d.ts.map

package/dist/filter/filter.ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.ast.d.ts","sourceRoot":"","sources":["../../src/filter/filter.ast.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzG;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,IAAI,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,YAAY,CAAC;IACnB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,sBAAsB,CAAC;IACjC,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CAC1C;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,cAAc,CAAC;CACvB;AAED,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,iBAAiB,GAAG,aAAa,GAAG,mBAAmB,CAAC"}

package/dist/filter/filter.parser.d.ts

@@ -0,0 +1,13 @@
+import type { ScimFilterNode } from './filter.ast.js';
+/**
+ * Parse a SCIM filter expression (RFC 7644 §3.4.2.2) into a typed AST.
+ * Throws a `400 invalidFilter` SCIM error on malformed input.
+ *
+ * Operator precedence (highest first):
+ *   1. parentheses, value-path brackets, `not(...)`
+ *   2. comparison
+ *   3. `and`
+ *   4. `or`
+ */
+export declare const parseScimFilter: (input: string) => ScimFilterNode;
+//# sourceMappingURL=filter.parser.d.ts.map

package/dist/filter/filter.parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.parser.d.ts","sourceRoot":"","sources":["../../src/filter/filter.parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAA0B,MAAM,iBAAiB,CAAC;AAG9E;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,cAU/C,CAAC"}

package/dist/filter/filter.tokenizer.d.ts

@@ -0,0 +1,14 @@
+export type ScimTokenKind = 'identifier' | 'string' | 'number' | 'true' | 'false' | 'null' | 'and' | 'or' | 'not' | 'lparen' | 'rparen' | 'lbracket' | 'rbracket' | 'op';
+export interface ScimToken {
+    kind: ScimTokenKind;
+    /** For `identifier`/`string`/`op`: the textual value. For `number`: numeric. */
+    value: string | number | boolean | null;
+    /** Source position where the token starts. */
+    start: number;
+}
+/**
+ * Tokenize a SCIM filter expression into a stream of {@link ScimToken}s.
+ * Throws a `400 invalidFilter` SCIM error on malformed input.
+ */
+export declare const tokenizeScimFilter: (input: string) => ScimToken[];
+//# sourceMappingURL=filter.tokenizer.d.ts.map

package/dist/filter/filter.tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.tokenizer.d.ts","sourceRoot":"","sources":["../../src/filter/filter.tokenizer.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,OAAO,GACP,MAAM,GACN,KAAK,GACL,IAAI,GACJ,KAAK,GACL,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,UAAU,GACV,IAAI,CAAC;AAET,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,gFAAgF;IAChF,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACxC,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;CACf;AAID;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,SAAS,EA0I3D,CAAC"}

package/dist/filter/index.d.ts

@@ -0,0 +1,4 @@
+export * from './filter.ast.js';
+export * from './filter.parser.js';
+export type { ScimToken, ScimTokenKind } from './filter.tokenizer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/filter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/filter/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from './types/scim.meta.js';
+export * from './types/scim.user.js';
+export * from './types/scim.group.js';
+export * from './types/list.response.js';
+export * from './types/patch.op.js';
+export * from './schemas/index.js';
+export * from './filter/index.js';
+export * from './patch/index.js';
+export * from './errors/scim.error.js';
+export * from './repositories/index.js';
+export * from './services/index.js';
+export * from './middleware/index.js';
+export * from './router/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,yBAAyB,CAAC;AAGxC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,mBAAmB,CAAC"}