@classytic/arc 2.11.4 → 2.13.1

package/dist/schemas/index.mjs

@@ -1,14 +1,34 @@
+import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
 import { TypeBoxValidatorCompiler } from "@fastify/type-provider-typebox";
 import { Type, Type as Type$1 } from "@sinclair/typebox";
 //#region src/schemas/index.ts
 /**
-* Paginated list response — matches Arc's runtime format:
-* `{ success, docs: [...], page, limit, total, pages, hasNext, hasPrev }`
+* Paginated list response — full union of every wire shape `toCanonicalList`
+* emits. Mirrors `PaginatedResult<T>` from `@classytic/repo-core/pagination`:
+*
+*   - `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
+*   - `{ method: 'keyset', data, limit, hasMore, next: string | null }`
+*   - `{ method: 'aggregate', ...same as offset }`
+*   - `{ data }` (bare list, no `method`)
+*
+* Use `ArcOffsetListResponse` / `ArcKeysetListResponse` /
+* `ArcAggregateListResponse` / `ArcBareListResponse` to pin a single
+* variant when your endpoint never emits the others. HTTP status
+* discriminates success vs error — no `success` field.
 */
 function ArcListResponse(itemSchema) {
+	return Type$1.Union([
+		ArcOffsetListResponse(itemSchema),
+		ArcKeysetListResponse(itemSchema),
+		ArcAggregateListResponse(itemSchema),
+		ArcBareListResponse(itemSchema)
+	]);
+}
+/** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
+function ArcOffsetListResponse(itemSchema) {
 	return Type$1.Object({
-		success: Type$1.Boolean(),
-		docs: Type$1.Array(itemSchema),
+		method: Type$1.Literal("offset"),
+		data: Type$1.Array(itemSchema),
 		page: Type$1.Integer(),
 		limit: Type$1.Integer(),
 		total: Type$1.Integer(),
@@ -17,48 +37,81 @@ function ArcListResponse(itemSchema) {
 		hasPrev: Type$1.Boolean()
 	});
 }
-/**
-* Single item response — `{ success, data: {...} }`
-*/
-function ArcItemResponse(itemSchema) {
+/** Keyset variant — `{ method: 'keyset', data, limit, hasMore, next: string | null }`. */
+function ArcKeysetListResponse(itemSchema) {
 	return Type$1.Object({
-		success: Type$1.Boolean(),
-		data: itemSchema
+		method: Type$1.Literal("keyset"),
+		data: Type$1.Array(itemSchema),
+		limit: Type$1.Integer(),
+		hasMore: Type$1.Boolean(),
+		next: Type$1.Union([Type$1.String(), Type$1.Null()])
 	});
 }
-/**
-* Mutation (create/update) response — `{ success, data: {...}, message? }`
-*/
-function ArcMutationResponse(itemSchema) {
+/** Aggregate variant — `{ method: 'aggregate', ...same as offset }`. */
+function ArcAggregateListResponse(itemSchema) {
 	return Type$1.Object({
-		success: Type$1.Boolean(),
-		data: itemSchema,
-		message: Type$1.Optional(Type$1.String())
+		method: Type$1.Literal("aggregate"),
+		data: Type$1.Array(itemSchema),
+		page: Type$1.Integer(),
+		limit: Type$1.Integer(),
+		total: Type$1.Integer(),
+		pages: Type$1.Integer(),
+		hasNext: Type$1.Boolean(),
+		hasPrev: Type$1.Boolean()
 	});
 }
+/** Bare variant — `{ data }`, no `method` discriminant. */
+function ArcBareListResponse(itemSchema) {
+	return Type$1.Object({ data: Type$1.Array(itemSchema) });
+}
 /**
-* Delete response — `{ success, message }`
+* Delete response — `{ message, id?, soft? }` raw at the top level.
 */
 function ArcDeleteResponse() {
 	return Type$1.Object({
-		success: Type$1.Boolean(),
-		message: Type$1.Optional(Type$1.String())
+		message: Type$1.String(),
+		id: Type$1.Optional(Type$1.String()),
+		soft: Type$1.Optional(Type$1.Boolean())
 	});
 }
 /**
-* Error response schema
+* Single field-scoped error detail — `Type.Unsafe<ErrorDetail>` over the
+* canonical JSON Schema `errorDetailSchema` from
+* `@classytic/repo-core/errors`. One schema constant, two adapters
+* (JSON-Schema + TypeBox), zero drift surface — the schema and the TS
+* type both come from repo-core.
+*
+* Exported standalone so hosts can embed it in custom 422 / 409 response
+* schemas.
+*/
+function ArcErrorDetail() {
+	return Type$1.Unsafe(errorDetailSchema);
+}
+/**
+* Error response schema — `Type.Unsafe<ErrorContract>` over the canonical
+* JSON Schema `errorContractSchema` from `@classytic/repo-core/errors`.
+* Same trick as `ArcErrorDetail`: the schema bytes and the TS type both
+* come from repo-core, so the JSON-Schema sibling
+* (`errorContractSchema`) and this TypeBox helper cannot drift —
+* literally one source.
 */
 function ArcErrorResponse() {
-	return Type$1.Object({
-		success: Type$1.Literal(false),
-		error: Type$1.String(),
-		code: Type$1.Optional(Type$1.String()),
-		message: Type$1.Optional(Type$1.String())
-	});
+	return Type$1.Unsafe(errorContractSchema);
 }
 /**
 * Standard pagination + sorting + filtering query parameters.
 * Matches Arc's list endpoint conventions.
+*
+* `select` accepts every shape `QueryResolver` preserves DB-agnostically
+* (gotcha #5):
+*
+*   - `string`  — `"name email -password"` (Mongoose space-separated)
+*   - `string[]` — `["name", "email", "-password"]` (Arc parser)
+*   - `Record<string, 0 | 1>` — `{ name: 1, email: 1, password: 0 }` (Mongo projection)
+*
+* Narrowing `select` to `string` would have rejected the array and
+* projection forms at the request-validation gate even though arc passes
+* them through unchanged.
 */
 function ArcPaginationQuery() {
 	return Type$1.Object({
@@ -72,9 +125,13 @@ function ArcPaginationQuery() {
 			default: 20
 		})),
 		sort: Type$1.Optional(Type$1.String()),
-		select: Type$1.Optional(Type$1.String()),
+		select: Type$1.Optional(Type$1.Union([
+			Type$1.String(),
+			Type$1.Array(Type$1.String()),
+			Type$1.Record(Type$1.String(), Type$1.Union([Type$1.Literal(0), Type$1.Literal(1)]))
+		])),
 		populate: Type$1.Optional(Type$1.Any())
 	}, { additionalProperties: true });
 }
 //#endregion
-export { ArcDeleteResponse, ArcErrorResponse, ArcItemResponse, ArcListResponse, ArcMutationResponse, ArcPaginationQuery, Type, TypeBoxValidatorCompiler };
+export { ArcAggregateListResponse, ArcBareListResponse, ArcDeleteResponse, ArcErrorDetail, ArcErrorResponse, ArcKeysetListResponse, ArcListResponse, ArcOffsetListResponse, ArcPaginationQuery, Type, TypeBoxValidatorCompiler };

package/dist/scim/index.d.mts

@@ -0,0 +1,264 @@
+import { FastifyPluginAsync, FastifyRequest } from "fastify";
+import { RepositoryLike } from "@classytic/repo-core/adapter";
+
+//#region src/scim/mapping.d.ts
+/**
+ * SCIM 2.0 ↔ arc resource mapping
+ *
+ * Most arc apps store users / orgs in a shape that doesn't match SCIM
+ * verbatim. This module owns the bidirectional translation:
+ *
+ *   - **Inbound** (`scimToResource`): SCIM JSON → arc resource shape
+ *   - **Outbound** (`resourceToScim`): arc resource → SCIM JSON
+ *
+ * Defaults track Better Auth's `user` / `organization` schema so apps using
+ * the BA overlay get a working SCIM endpoint with zero mapping config.
+ */
+/**
+ * Mapping spec for a single SCIM resource type. Apps override only the
+ * fields that diverge from the BA defaults.
+ */
+interface ScimResourceMapping {
+  /** SCIM resource schema URI (e.g. `urn:ietf:params:scim:schemas:core:2.0:User`). */
+  schema: string;
+  /**
+   * SCIM attribute → backend field. Used by both filter parser and
+   * outbound serializer. Omit an attribute to mark it non-filterable.
+   */
+  attributes: Record<string, string>;
+  /** Inverse for outbound serialization — built from `attributes` by default. */
+  reverseAttributes?: Record<string, string>;
+  /** Custom inbound transform — runs after attribute mapping. */
+  fromScim?: (scim: Record<string, unknown>, mapped: Record<string, unknown>) => Record<string, unknown>;
+  /** Custom outbound transform — runs after attribute mapping. */
+  toScim?: (resource: Record<string, unknown>, mapped: Record<string, unknown>) => Record<string, unknown>;
+}
+declare const SCIM_USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User";
+declare const SCIM_GROUP_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Group";
+declare const SCIM_ENTERPRISE_USER_SCHEMA = "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User";
+declare const DEFAULT_USER_MAPPING: ScimResourceMapping;
+declare const DEFAULT_GROUP_MAPPING: ScimResourceMapping;
+/** Translate inbound SCIM JSON → resource shape. */
+declare function scimToResource(scim: Record<string, unknown>, mapping: ScimResourceMapping): Record<string, unknown>;
+/** Translate resource → SCIM JSON. */
+declare function resourceToScim(resource: Record<string, unknown>, mapping: ScimResourceMapping, baseUrl: string): Record<string, unknown>;
+//#endregion
+//#region src/scim/types.d.ts
+/**
+ * One arc resource bound into the SCIM surface.
+ *
+ * Pass the resource definition you already register with arc — the plugin
+ * reads `resource.adapter.repository`. Whatever kit plugins (`auditPlugin`,
+ * `multiTenantPlugin`, `fieldFilterPlugin`, …) you wire at construction
+ * time fire for SCIM the same way they fire for arc REST, because both
+ * surfaces call the same repository methods.
+ */
+interface ScimResourceBinding {
+  resource: {
+    name: string;
+    adapter: {
+      repository: RepositoryLike;
+    };
+  };
+  /**
+   * Override the SCIM ↔ resource mapping. Defaults to the BA-aligned shape
+   * (BA `user.email` ↔ SCIM `userName`, etc.). Pass a partial — only the
+   * diverging fields need to be overridden.
+   */
+  mapping?: Partial<ScimResourceMapping>;
+}
+/**
+ * Configuration for `scimPlugin`. One of `bearer` / `verify` is required.
+ */
+interface ScimPluginOptions {
+  /** User resource binding (mounts `/scim/v2/Users`). */
+  users: ScimResourceBinding;
+  /** Group / organization resource binding (mounts `/scim/v2/Groups`). Optional. */
+  groups?: ScimResourceBinding;
+  /**
+   * Static bearer token. Mutually exclusive with `verify` — pass one or the other.
+   */
+  bearer?: string;
+  /**
+   * Custom verifier — runs on every SCIM request. Return `true` to accept,
+   * `false` (or throw) to reject. Use for OIDC-secured deployments where
+   * the SCIM token is a short-lived JWT.
+   */
+  verify?: (request: FastifyRequest) => boolean | Promise<boolean>;
+  /**
+   * Mount prefix. Defaults to `/scim/v2` — RFC-compliant, what every IdP expects.
+   */
+  prefix?: string;
+  /**
+   * Maximum page size SCIM clients can request via `count` — defaults to 200
+   * (Okta's default). Larger values may degrade IdP-side reconciliation.
+   */
+  maxResults?: number;
+  /**
+   * Optional structured-log hook — called once per SCIM request with a
+   * canonical observability payload. Defaults to `request.log.info(...)`.
+   */
+  observe?: (event: ScimObservedEvent) => void;
+}
+/**
+ * Single observability event emitted per SCIM request. Stable shape so
+ * downstream metrics / logging stacks can pin dashboards without arc-version
+ * drift.
+ */
+interface ScimObservedEvent {
+  /** SCIM resource type (`Users` / `Groups`) or `discovery` for meta endpoints. */
+  resourceType: "Users" | "Groups" | "discovery";
+  /**
+   * SCIM operation. CRUD: `list`, `get`, `create`, `replace`, `patch`, `delete`.
+   * Discovery: `discovery.<endpoint>`.
+   */
+  op: string;
+  /** HTTP status code returned. */
+  status: number;
+  /** Wall-clock duration in ms (rounded). */
+  durationMs: number;
+  /** SCIM error type when the request failed (`invalidFilter`, etc.). Undefined on success. */
+  scimType?: string;
+  /** Path component (`/Users`, `/Users/:id`, `/ServiceProviderConfig`, …). */
+  path: string;
+}
+//#endregion
+//#region src/scim/errors.d.ts
+/**
+ * SCIM 2.0 error responses (RFC 7644 §3.12)
+ *
+ * Wire shape:
+ * ```json
+ * {
+ *   "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
+ *   "status": "400",
+ *   "scimType": "invalidFilter",
+ *   "detail": "Attribute 'xyz' is not filterable"
+ * }
+ * ```
+ */
+type ScimType = "invalidFilter" | "tooMany" | "uniqueness" | "mutability" | "invalidSyntax" | "invalidPath" | "noTarget" | "invalidValue" | "invalidVers" | "sensitive";
+declare class ScimError extends Error {
+  readonly statusCode: number;
+  readonly scimType?: ScimType;
+  constructor(statusCode: number, scimType: ScimType | undefined, detail: string);
+  toResponse(): Record<string, unknown>;
+}
+//#endregion
+//#region src/scim/filter.d.ts
+/**
+ * SCIM 2.0 filter language parser (RFC 7644 §3.4.2.2)
+ *
+ * Translates SCIM filter expressions into arc's query DSL so existing
+ * resources can serve `/scim/v2/Users?filter=...` without per-resource glue.
+ *
+ * Supports the subset every IdP actually emits in production:
+ *   - Comparison ops: eq, ne, co, sw, ew, gt, ge, lt, le, pr (present)
+ *   - Logical: and, or, not
+ *   - Grouping: ( )
+ *   - Attribute paths: `userName`, `name.familyName`, `emails[type eq "work"].value`
+ *
+ * Out of scope (yields a 400 with a clear reason):
+ *   - Complex value paths beyond one level
+ *   - Sub-attribute traversal in operands
+ *
+ * @example
+ * parseScimFilter('userName eq "alice@acme.com"')
+ *   → { userName: 'alice@acme.com' }
+ *
+ * parseScimFilter('active eq true and name.familyName sw "S"')
+ *   → { $and: [{ active: true }, { 'name.familyName': { $regex: '^S' } }] }
+ */
+type FilterNode = {
+  kind: "and";
+  left: FilterNode;
+  right: FilterNode;
+} | {
+  kind: "or";
+  left: FilterNode;
+  right: FilterNode;
+} | {
+  kind: "not";
+  child: FilterNode;
+} | {
+  kind: "compare";
+  attr: string;
+  op: "eq" | "ne" | "co" | "sw" | "ew" | "gt" | "ge" | "lt" | "le";
+  value: string | number | boolean | null;
+} | {
+  kind: "present";
+  attr: string;
+};
+/**
+ * Parse a SCIM 2.0 filter expression and translate to arc/Mongo query shape.
+ *
+ * @param filter Raw filter string from `?filter=...`
+ * @param mapAttr Mapping function: SCIM attr → backend field name. Return
+ *   `undefined` to deny (yields 400 invalidFilter). Use `IDENTITY_MAP` when
+ *   the resource exposes SCIM-named attributes directly.
+ */
+declare function parseScimFilter(filter: string, mapAttr: (scimAttr: string) => string | undefined): Record<string, unknown>;
+/** Pass-through mapper for resources that already use SCIM attribute names. */
+declare const IDENTITY_MAP: (a: string) => string;
+//#endregion
+//#region src/scim/patch.d.ts
+/**
+ * SCIM 2.0 PATCH parser (RFC 7644 §3.5.2)
+ *
+ * Translates SCIM PATCH operations into a flat update object the resource's
+ * existing PATCH handler can apply. Supports the three operations every IdP
+ * actually emits: `add`, `replace`, `remove`.
+ *
+ * **Path support**:
+ *   - Simple attribute: `userName` → `{ userName: <value> }`
+ *   - Sub-attribute: `name.familyName` → `{ 'name.familyName': <value> }`
+ *   - No path (op-level value): `replace` with object value → spread into update
+ *   - Multi-value with filter: `emails[type eq "work"].value` — parsed but
+ *     translated to a `$set` on the matching array element by index lookup
+ *     (host resolves index via the supplied `lookupArrayIndex` callback)
+ *
+ * @example
+ * parseScimPatch({
+ *   schemas: ['urn:ietf:params:scim:api:messages:2.0:PatchOp'],
+ *   Operations: [
+ *     { op: 'replace', path: 'displayName', value: 'Alice S.' },
+ *     { op: 'add',     path: 'emails', value: [{ type: 'work', value: 'a@x.com' }] },
+ *     { op: 'remove',  path: 'emails[type eq "old"]' },
+ *   ],
+ * })
+ *   → { $set: { displayName: 'Alice S.' }, $push: { emails: ... }, $pull: { emails: ... } }
+ */
+interface ScimPatchRequest {
+  schemas?: readonly string[];
+  Operations?: readonly ScimPatchOperation[];
+  operations?: readonly ScimPatchOperation[];
+}
+interface ScimPatchOperation {
+  op: string;
+  path?: string;
+  value?: unknown;
+}
+interface ScimUpdate {
+  /** Direct field assignments → resource's `update` payload. */
+  $set: Record<string, unknown>;
+  /** Multi-value array additions → `$push` on the field. */
+  $push: Record<string, unknown>;
+  /** Multi-value removals — caller resolves which element. */
+  $pull: Record<string, unknown>;
+  /** Field unset (remove without filter). */
+  $unset: Record<string, true>;
+}
+declare function parseScimPatch(req: ScimPatchRequest): ScimUpdate;
+/**
+ * Flatten a {@link ScimUpdate} into a plain `{ field: value }` object suitable
+ * for arc resource `PATCH` handlers that expect a partial document. Drops
+ * `$push` / `$pull` / `$unset` semantics — use {@link parseScimPatch} directly
+ * when the host needs the full op stream (e.g. to issue array mutations).
+ */
+declare function scimUpdateToFlatPatch(update: ScimUpdate): Record<string, unknown>;
+//#endregion
+//#region src/scim/index.d.ts
+declare const scimPlugin: FastifyPluginAsync<ScimPluginOptions>;
+declare const _default: FastifyPluginAsync<ScimPluginOptions>;
+//#endregion
+export { DEFAULT_GROUP_MAPPING, DEFAULT_USER_MAPPING, type FilterNode, IDENTITY_MAP, SCIM_ENTERPRISE_USER_SCHEMA, SCIM_GROUP_SCHEMA, SCIM_USER_SCHEMA, ScimError, type ScimObservedEvent, type ScimPatchRequest, type ScimPluginOptions, type ScimResourceBinding, type ScimResourceMapping, type ScimType, type ScimUpdate, _default as default, parseScimFilter, parseScimPatch, resourceToScim, scimPlugin, scimToResource, scimUpdateToFlatPatch };