@_mustachio/openauth 0.12.0 → 0.13.0

package/src/domain/scim/resource.ts

@@ -0,0 +1,358 @@
+/**
+ * SCIM resource shapes — validation in, serialization out, and the
+ * error envelope.
+ *
+ * RFC 7643 defines the User schema; RFC 7644 defines the message
+ * envelopes. Both are picky in ways that are easy to get subtly wrong
+ * and that Okta's validator checks, so the details here are asserted in
+ * tests rather than assumed:
+ *
+ *   - `status` in an Error is a **string**, not a number.
+ *   - `ListResponse` uses `Resources` with a capital R.
+ *   - `startIndex` is **1-based**.
+ *   - `meta.location` must be an absolute URL; Okta reads it.
+ *
+ * Pure: no I/O, no port access.
+ */
+import type {
+  ScimEnterpriseUser,
+  ScimGroupMember,
+  ScimGroupRecord,
+  ScimGroupWrite,
+  ScimMultiValue,
+  ScimName,
+  ScimUserRecord,
+  ScimUserWrite,
+} from "../../types/scim"
+import { err, ok, type Result } from "../../types/result"
+
+export const SCIM_USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User"
+export const SCIM_GROUP_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Group"
+export const SCIM_ENTERPRISE_SCHEMA =
+  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
+export const SCIM_LIST_SCHEMA =
+  "urn:ietf:params:scim:api:messages:2.0:ListResponse"
+export const SCIM_ERROR_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:Error"
+export const SCIM_PATCH_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:PatchOp"
+
+/** RFC 7644 §3.12 `scimType` values we emit. */
+export type ScimErrorType =
+  | "invalidFilter"
+  | "invalidPath"
+  | "invalidSyntax"
+  | "invalidValue"
+  | "mutability"
+  | "noTarget"
+  | "uniqueness"
+  | "tooMany"
+
+export type ScimValidationError = {
+  status: number
+  detail: string
+  scimType?: ScimErrorType
+}
+
+/** RFC 7644 §3.12 error envelope. */
+export function scimErrorBody(
+  status: number,
+  detail: string,
+  scimType?: ScimErrorType,
+): Record<string, unknown> {
+  return {
+    schemas: [SCIM_ERROR_SCHEMA],
+    // A string, per the RFC's own examples — a number here is a common
+    // implementation bug and Okta's validator notices.
+    status: String(status),
+    ...(scimType !== undefined ? { scimType } : {}),
+    detail,
+  }
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v)
+
+const asString = (v: unknown): string | undefined =>
+  typeof v === "string" && v.length > 0 ? v : undefined
+
+function parseName(v: unknown): ScimName | undefined {
+  if (!isRecord(v)) return undefined
+  const out: ScimName = {}
+  for (const k of [
+    "formatted",
+    "familyName",
+    "givenName",
+    "middleName",
+    "honorificPrefix",
+    "honorificSuffix",
+  ] as const) {
+    const s = asString(v[k])
+    if (s !== undefined) out[k] = s
+  }
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+function parseMultiValues(v: unknown): ScimMultiValue[] | undefined {
+  if (!Array.isArray(v)) return undefined
+  const out: ScimMultiValue[] = []
+  for (const entry of v) {
+    if (!isRecord(entry)) continue
+    const value = asString(entry["value"])
+    if (value === undefined) continue
+    const type = asString(entry["type"])
+    const primary = entry["primary"]
+    out.push({
+      value,
+      ...(type !== undefined ? { type } : {}),
+      ...(typeof primary === "boolean" ? { primary } : {}),
+    })
+  }
+  return out.length > 0 ? out : undefined
+}
+
+function parseEnterprise(v: unknown): ScimEnterpriseUser | undefined {
+  if (!isRecord(v)) return undefined
+  const out: ScimEnterpriseUser = {}
+  for (const k of [
+    "employeeNumber",
+    "costCenter",
+    "organization",
+    "division",
+    "department",
+  ] as const) {
+    const s = asString(v[k])
+    if (s !== undefined) out[k] = s
+  }
+  const mgr = v["manager"]
+  if (isRecord(mgr)) {
+    const value = asString(mgr["value"])
+    const displayName = asString(mgr["displayName"])
+    if (value !== undefined || displayName !== undefined) {
+      out.manager = {
+        ...(value !== undefined ? { value } : {}),
+        ...(displayName !== undefined ? { displayName } : {}),
+      }
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/**
+ * Validate a `POST` / `PUT` user payload into a `ScimUserWrite`.
+ *
+ * Unknown attributes are ignored rather than rejected: SCIM clients send
+ * plenty the spec allows and we do not model, and failing the whole
+ * provisioning run over an extra field would be hostile. The two
+ * exceptions are hard errors — a missing `userName`, which leaves the
+ * record unidentifiable, and `password`, which we refuse to handle at
+ * all rather than accept and drop.
+ */
+export function parseUserWrite(
+  body: unknown,
+): Result<ScimUserWrite, ScimValidationError> {
+  if (!isRecord(body)) {
+    return err({
+      status: 400,
+      scimType: "invalidSyntax",
+      detail: "request body must be a JSON object",
+    })
+  }
+
+  if (body["password"] !== undefined) {
+    return err({
+      status: 400,
+      scimType: "invalidValue",
+      detail:
+        "this Service Provider does not accept 'password' over SCIM; " +
+        "credentials are managed by the authentication methods, not the " +
+        "directory feed",
+    })
+  }
+
+  const userName = asString(body["userName"])
+  if (userName === undefined) {
+    return err({
+      status: 400,
+      scimType: "invalidValue",
+      detail: "userName is required and must be a non-empty string",
+    })
+  }
+
+  const activeRaw = body["active"]
+  if (activeRaw !== undefined && typeof activeRaw !== "boolean") {
+    return err({
+      status: 400,
+      scimType: "invalidValue",
+      detail: "active must be a boolean",
+    })
+  }
+
+  const externalId = asString(body["externalId"])
+  const displayName = asString(body["displayName"])
+  const name = parseName(body["name"])
+  const emails = parseMultiValues(body["emails"])
+  const phoneNumbers = parseMultiValues(body["phoneNumbers"])
+  const enterprise = parseEnterprise(body[SCIM_ENTERPRISE_SCHEMA])
+
+  return ok({
+    userName,
+    // SCIM defaults `active` to true on create. Resolving the default
+    // here keeps the semantics in one place instead of in every host.
+    active: activeRaw === undefined ? true : activeRaw,
+    ...(externalId !== undefined ? { externalId } : {}),
+    ...(displayName !== undefined ? { displayName } : {}),
+    ...(name !== undefined ? { name } : {}),
+    ...(emails !== undefined ? { emails } : {}),
+    ...(phoneNumbers !== undefined ? { phoneNumbers } : {}),
+    ...(enterprise !== undefined ? { enterprise } : {}),
+  })
+}
+
+const iso = (ms: number | undefined): string | undefined =>
+  ms === undefined ? undefined : new Date(ms).toISOString()
+
+/** Serialize a host record into a SCIM User resource. */
+export function serializeUser(
+  user: ScimUserRecord,
+  baseUrl: string,
+): Record<string, unknown> {
+  const schemas = [SCIM_USER_SCHEMA]
+  if (user.enterprise !== undefined) schemas.push(SCIM_ENTERPRISE_SCHEMA)
+
+  const created = iso(user.createdAt)
+  const lastModified = iso(user.updatedAt)
+
+  return {
+    schemas,
+    id: user.id,
+    ...(user.externalId !== undefined ? { externalId: user.externalId } : {}),
+    userName: user.userName,
+    ...(user.name !== undefined ? { name: user.name } : {}),
+    ...(user.displayName !== undefined
+      ? { displayName: user.displayName }
+      : {}),
+    ...(user.emails !== undefined ? { emails: user.emails } : {}),
+    ...(user.phoneNumbers !== undefined
+      ? { phoneNumbers: user.phoneNumbers }
+      : {}),
+    active: user.active,
+    ...(user.enterprise !== undefined
+      ? { [SCIM_ENTERPRISE_SCHEMA]: user.enterprise }
+      : {}),
+    meta: {
+      resourceType: "User",
+      ...(created !== undefined ? { created } : {}),
+      ...(lastModified !== undefined ? { lastModified } : {}),
+      location: `${baseUrl}/Users/${encodeURIComponent(user.id)}`,
+    },
+  }
+}
+
+/** RFC 7644 §3.4.2 ListResponse. */
+export function serializeList(
+  users: ScimUserRecord[],
+  totalResults: number,
+  startIndex: number,
+  baseUrl: string,
+): Record<string, unknown> {
+  return {
+    schemas: [SCIM_LIST_SCHEMA],
+    totalResults,
+    startIndex,
+    itemsPerPage: users.length,
+    // Capital R — the spec's own casing, and a frequent interop bug.
+    Resources: users.map((u) => serializeUser(u, baseUrl)),
+  }
+}
+
+function parseMembers(v: unknown): ScimGroupMember[] | undefined {
+  // Some IdPs send a bare object where the spec wants an array.
+  const list = Array.isArray(v) ? v : isRecord(v) ? [v] : undefined
+  if (list === undefined) return undefined
+  const out: ScimGroupMember[] = []
+  for (const entry of list) {
+    if (!isRecord(entry)) continue
+    const value = asString(entry["value"])
+    if (value === undefined) continue
+    const display = asString(entry["display"])
+    out.push({ value, ...(display !== undefined ? { display } : {}) })
+  }
+  return out
+}
+
+export { parseMembers }
+
+/** Validate a `POST` / `PUT` group payload. */
+export function parseGroupWrite(
+  body: unknown,
+): Result<ScimGroupWrite, ScimValidationError> {
+  if (!isRecord(body)) {
+    return err({
+      status: 400,
+      scimType: "invalidSyntax",
+      detail: "request body must be a JSON object",
+    })
+  }
+  const displayName = asString(body["displayName"])
+  if (displayName === undefined) {
+    return err({
+      status: 400,
+      scimType: "invalidValue",
+      detail: "displayName is required and must be a non-empty string",
+    })
+  }
+  const externalId = asString(body["externalId"])
+  const members = parseMembers(body["members"])
+  return ok({
+    displayName,
+    ...(externalId !== undefined ? { externalId } : {}),
+    ...(members !== undefined ? { members } : {}),
+  })
+}
+
+/** Serialize a host group record into a SCIM Group resource. */
+export function serializeGroup(
+  group: ScimGroupRecord,
+  baseUrl: string,
+): Record<string, unknown> {
+  const created = iso(group.createdAt)
+  const lastModified = iso(group.updatedAt)
+  return {
+    schemas: [SCIM_GROUP_SCHEMA],
+    id: group.id,
+    ...(group.externalId !== undefined ? { externalId: group.externalId } : {}),
+    displayName: group.displayName,
+    // Omitted entirely when the host did not load membership — `[]`
+    // would tell the client the group has been emptied.
+    ...(group.members !== undefined
+      ? {
+          members: group.members.map((m) => ({
+            value: m.value,
+            ...(m.display !== undefined ? { display: m.display } : {}),
+            $ref: `${baseUrl}/Users/${encodeURIComponent(m.value)}`,
+            type: "User",
+          })),
+        }
+      : {}),
+    meta: {
+      resourceType: "Group",
+      ...(created !== undefined ? { created } : {}),
+      ...(lastModified !== undefined ? { lastModified } : {}),
+      location: `${baseUrl}/Groups/${encodeURIComponent(group.id)}`,
+    },
+  }
+}
+
+export function serializeGroupList(
+  groups: ScimGroupRecord[],
+  totalResults: number,
+  startIndex: number,
+  baseUrl: string,
+): Record<string, unknown> {
+  return {
+    schemas: [SCIM_LIST_SCHEMA],
+    totalResults,
+    startIndex,
+    itemsPerPage: groups.length,
+    Resources: groups.map((g) => serializeGroup(g, baseUrl)),
+  }
+}

package/src/http/context.ts

@@ -11,6 +11,7 @@ import type { AuditLog } from "../ports/audit-log"
 import type { ConfigStore } from "../ports/config-store"
 import type { KeyStore } from "../ports/key-store"
 import type { MethodStore } from "../ports/method-store"
+import type { ScimDirectory } from "../ports/scim-directory"
 import type { SessionStore } from "../ports/session-store"
 import type { TokenStore } from "../ports/token-store"
 import type { MethodCache } from "../domain/method-cache"
@@ -43,6 +44,8 @@ export type HttpDeps = {
   keyStore: KeyStore
   methodStore?: MethodStore
   auditLog?: AuditLog
+  /** See `IdPOptions.scimDirectory`. Absent ⇒ `/scim/v2/*` answers 501. */
+  scimDirectory?: ScimDirectory
   methodCache: MethodCache
   stateKeys: StateKeyRing
   /** Resolves the issuer URL — string or per-request function. */

package/src/http/handlers/authorize.ts

@@ -340,4 +340,3 @@ function clearFlowCookie() {
     maxAge: 0,
   }
 }
-

package/src/http/handlers/method-route.ts

@@ -45,10 +45,7 @@ export function makeMethodRouteHandler(deps: HttpDeps) {
         const httpMethod =
           c.req.method.toUpperCase() === "POST" ? "POST" : "GET"
         const routeKey = `${httpMethod} ${subPath}` as RouteKey
-        const resolved = await deps.methodCache.resolve(
-          tenant.config,
-          methodId,
-        )
+        const resolved = await deps.methodCache.resolve(tenant.config, methodId)
         if (
           !isErr(resolved) &&
           resolved.value.publicRoutes?.includes(routeKey)

package/src/http/handlers/scim.ts

@@ -0,0 +1,107 @@
+/**
+ * `/scim/v2/*` — SCIM 2.0 provisioning.
+ *
+ * Thin by design: parse the request into plain data, hand it to
+ * `handleScimRequest`, serialize the result. Every decision — auth,
+ * routing, validation, status codes — lives in the domain, so the whole
+ * SCIM surface is testable without Hono.
+ *
+ * Responses carry `application/scim+json` per RFC 7644 §3.1.
+ */
+import { handleScimRequest } from "../../domain/scim/handle"
+import { scimErrorBody } from "../../domain/scim/resource"
+
+import type { HttpContext, HttpDeps } from "../context"
+
+const SCIM_CONTENT_TYPE = "application/scim+json;charset=utf-8"
+const MOUNT = "/scim/v2"
+
+function scimResponse(
+  status: number,
+  body: Record<string, unknown> | null,
+  extra: Record<string, string> = {},
+): Response {
+  if (body === null || status === 204) {
+    return new Response(null, { status, headers: extra })
+  }
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": SCIM_CONTENT_TYPE,
+      // Provisioning responses are per-tenant and mutable; never cached.
+      "cache-control": "no-store",
+      ...extra,
+    },
+  })
+}
+
+export function makeScimHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    if (!deps.scimDirectory) {
+      return scimResponse(
+        501,
+        scimErrorBody(
+          501,
+          "SCIM is not configured on this deployment (no scimDirectory " +
+            "was supplied to createIdP)",
+        ),
+      )
+    }
+
+    const tenant = c.get("tenant")
+    if (!tenant) {
+      // The tenant middleware could not resolve a partition. Answer the
+      // same way an unknown token does, so this endpoint never reveals
+      // which tenants exist.
+      return scimResponse(
+        403,
+        scimErrorBody(403, "SCIM provisioning is not enabled for this tenant"),
+      )
+    }
+
+    const url = new URL(c.req.url)
+    const path = url.pathname.startsWith(MOUNT)
+      ? url.pathname.slice(MOUNT.length)
+      : url.pathname
+
+    const method = c.req.method.toUpperCase()
+
+    // Only read a body for methods that carry one. An unparseable body
+    // becomes `null` and the domain reports it as invalid syntax with
+    // the right SCIM envelope, rather than throwing here.
+    let body: unknown = null
+    if (method === "POST" || method === "PUT" || method === "PATCH") {
+      const raw = await c.req.raw.text()
+      if (raw.length > 0) {
+        try {
+          body = JSON.parse(raw)
+        } catch {
+          return scimResponse(
+            400,
+            scimErrorBody(
+              400,
+              "request body is not valid JSON",
+              "invalidSyntax",
+            ),
+          )
+        }
+      }
+    }
+
+    const issuer = c.get("issuerUrl")
+    const base = issuer.endsWith("/") ? issuer.slice(0, -1) : issuer
+
+    const result = await handleScimRequest({
+      tenant,
+      method,
+      path,
+      query: url.searchParams,
+      body,
+      authorization: c.req.header("authorization") ?? null,
+      baseUrl: `${base}${MOUNT}`,
+      directory: deps.scimDirectory,
+    })
+
+    return scimResponse(result.status, result.body, result.headers ?? {})
+  }
+}

package/src/http/middleware/tenant.ts

@@ -32,7 +32,47 @@ import {
   authorizeDirectErrorResponse,
   tokenEndpointErrorResponse,
 } from "../errors"
-import { authError } from "../../types/error"
+import { authError, type AuthError } from "../../types/error"
+
+/**
+ * SCIM has its own media type and error envelope, and its own
+ * disclosure rule: an unauthenticated caller must not be able to tell an
+ * unknown tenant from a known one. The shared OAuth error response
+ * defeats both — it answers `400 application/json` with the
+ * tenant-not-found text, which is visibly different from the `403` a
+ * configured-but-SCIM-disabled tenant gets.
+ *
+ * So SCIM paths collapse every tenant-resolution failure onto the same
+ * `403` the domain layer emits for "SCIM is not enabled here". A store
+ * failure is still distinguishable as a 500, because that is an
+ * operational fault rather than a fact about which tenants exist.
+ */
+function isScimPath(pathname: string): boolean {
+  return pathname === "/scim/v2" || pathname.startsWith("/scim/v2/")
+}
+
+function scimTenantErrorResponse(error: AuthError): Response {
+  const operational =
+    error.code === "server_error" || error.code === "internal_error"
+  const status = operational ? 500 : 403
+  const detail = operational
+    ? "the configuration store backing this endpoint failed the request"
+    : "SCIM provisioning is not enabled for this tenant"
+  return new Response(
+    JSON.stringify({
+      schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+      status: String(status),
+      detail,
+    }),
+    {
+      status,
+      headers: {
+        "content-type": "application/scim+json;charset=utf-8",
+        "cache-control": "no-store",
+      },
+    },
+  )
+}
 
 function isCallbackPath(pathname: string): boolean {
   return pathname.startsWith("/cb/")
@@ -89,6 +129,9 @@ export function tenantMiddleware(deps: HttpDeps): MiddlewareHandler<HttpEnv> {
       if (url.pathname === "/authorize") {
         return authorizeDirectErrorResponse(resolved.error)
       }
+      if (isScimPath(url.pathname)) {
+        return scimTenantErrorResponse(resolved.error)
+      }
       return tokenEndpointErrorResponse(resolved.error)
     }
     const tenantId = resolved.value
@@ -101,6 +144,9 @@ export function tenantMiddleware(deps: HttpDeps): MiddlewareHandler<HttpEnv> {
       if (url.pathname === "/authorize") {
         return authorizeDirectErrorResponse(err)
       }
+      if (isScimPath(url.pathname)) {
+        return scimTenantErrorResponse(cfg.error)
+      }
       return tokenEndpointErrorResponse(err)
     }
     const custom = deps.buildCustomContext

package/src/http/router.ts

@@ -24,6 +24,7 @@ import { makeDiscoveryHandler, makeJwksHandler } from "./handlers/metadata"
 import { makeMethodRouteHandler } from "./handlers/method-route"
 import { makeParHandler } from "./handlers/par"
 import { makeRegisterHandler } from "./handlers/register"
+import { makeScimHandler } from "./handlers/scim"
 import { makeIntrospectHandler, makeRevokeHandler } from "./handlers/revocation"
 import { makeTokenHandler } from "./handlers/token"
 import { makeUserinfoHandler } from "./handlers/userinfo"
@@ -71,6 +72,14 @@ export function buildRouter(deps: HttpDeps): Hono<HttpEnv> {
   app.get("/end_session", makeEndSessionHandler(deps))
   app.post("/end_session", makeEndSessionHandler(deps))
 
+  // SCIM 2.0 provisioning. Tenant resolved by the standard middleware;
+  // the per-connection bearer token is then verified against that
+  // tenant's config in the domain layer (SCIM-AD4). A single `all`
+  // mount keeps Hono out of SCIM's routing, which lives in
+  // `domain/scim/handle.ts`.
+  app.use("/scim/v2/*", tenantMiddleware(deps))
+  app.all("/scim/v2/*", makeScimHandler(deps))
+
   // RFC 9126 Pushed Authorization Requests.
   app.use("/par", tenantMiddleware(deps))
   app.post("/par", makeParHandler(deps))

package/src/index.ts

@@ -98,6 +98,25 @@ export type {
   SigningKey,
 } from "./ports/key-store"
 export type { MethodStore } from "./ports/method-store"
+export type { ScimDirectory } from "./ports/scim-directory"
+export type {
+  ScimConfig,
+  ScimEnterpriseUser,
+  ScimGroupMember,
+  ScimGroupPatch,
+  ScimGroupQuery,
+  ScimGroupRecord,
+  ScimGroupWrite,
+  ScimFilter,
+  ScimFilterAttribute,
+  ScimMultiValue,
+  ScimName,
+  ScimPage,
+  ScimUserPatch,
+  ScimUserQuery,
+  ScimUserRecord,
+  ScimUserWrite,
+} from "./types/scim"
 export type {
   ParRecord,
   SessionRecord,
@@ -241,6 +260,7 @@ export function createIdP(opts: IdPOptions): IdP {
     sessionStore: opts.sessionStore,
     keyStore: opts.keyStore,
     ...(opts.methodStore ? { methodStore: opts.methodStore } : {}),
+    ...(opts.scimDirectory ? { scimDirectory: opts.scimDirectory } : {}),
     ...(auditLog ? { auditLog } : {}),
     methodCache,
     stateKeys: opts.stateKeys,