@objectstack/spec 0.3.3 → 0.4.1

package/dist/auth/scim.zod.js

@@ -0,0 +1,811 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCIM = exports.SCIMPatchRequestSchema = exports.SCIMPatchOperationSchema = exports.SCIMErrorSchema = exports.SCIMListResponseSchema = exports.SCIMGroupSchema = exports.SCIMMemberReferenceSchema = exports.SCIMUserSchema = exports.SCIMEnterpriseUserSchema = exports.SCIMGroupReferenceSchema = exports.SCIMAddressSchema = exports.SCIMPhoneNumberSchema = exports.SCIMEmailSchema = exports.SCIMNameSchema = exports.SCIMMetaSchema = exports.SCIM_SCHEMAS = void 0;
+const zod_1 = require("zod");
+/**
+ * # SCIM 2.0 Protocol Implementation
+ *
+ * System for Cross-domain Identity Management (SCIM) 2.0 specification
+ * implementation for ObjectStack.
+ *
+ * ## Overview
+ *
+ * SCIM 2.0 is an HTTP-based protocol for managing user and group identities
+ * across domains. It provides a standardized REST API for user provisioning,
+ * de-provisioning, and synchronization.
+ *
+ * ## Use Cases
+ *
+ * 1. **Enterprise SSO Integration**
+ *    - Integrate with Okta, Azure AD, OneLogin
+ *    - Automatic user provisioning from corporate directory
+ *    - Just-in-Time (JIT) user creation on first login
+ *
+ * 2. **User Lifecycle Management**
+ *    - Automatically create users when they join organization
+ *    - Update user attributes when they change roles
+ *    - Deactivate users when they leave organization
+ *
+ * 3. **Group/Department Synchronization**
+ *    - Sync organizational structure from AD/LDAP
+ *    - Maintain group memberships automatically
+ *    - Map corporate roles to application permissions
+ *
+ * 4. **Compliance & Audit**
+ *    - Maintain accurate user directory
+ *    - Track all identity changes
+ *    - Meet SOX/HIPAA requirements for user management
+ *
+ * ## Specification References
+ *
+ * - **RFC 7643**: SCIM Core Schema
+ * - **RFC 7644**: SCIM Protocol
+ * - **RFC 7642**: SCIM Requirements
+ *
+ * ## Industry Implementations
+ *
+ * - **Okta**: Leading SCIM provider
+ * - **Azure AD**: Microsoft's identity platform
+ * - **OneLogin**: Enterprise SSO provider
+ * - **Google Workspace**: Google's identity management
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7643
+ * @see https://datatracker.ietf.org/doc/html/rfc7644
+ */
+/**
+ * SCIM Schema URIs
+ * Standard schema identifiers defined in RFC 7643
+ */
+exports.SCIM_SCHEMAS = {
+    USER: 'urn:ietf:params:scim:schemas:core:2.0:User',
+    GROUP: 'urn:ietf:params:scim:schemas:core:2.0:Group',
+    ENTERPRISE_USER: 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User',
+    RESOURCE_TYPE: 'urn:ietf:params:scim:schemas:core:2.0:ResourceType',
+    SERVICE_PROVIDER_CONFIG: 'urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig',
+    SCHEMA: 'urn:ietf:params:scim:schemas:core:2.0:Schema',
+    LIST_RESPONSE: 'urn:ietf:params:scim:api:messages:2.0:ListResponse',
+    PATCH_OP: 'urn:ietf:params:scim:api:messages:2.0:PatchOp',
+    BULK_REQUEST: 'urn:ietf:params:scim:api:messages:2.0:BulkRequest',
+    BULK_RESPONSE: 'urn:ietf:params:scim:api:messages:2.0:BulkResponse',
+    ERROR: 'urn:ietf:params:scim:api:messages:2.0:Error',
+};
+/**
+ * SCIM Meta Schema
+ * Common metadata for all SCIM resources
+ */
+exports.SCIMMetaSchema = zod_1.z.object({
+    /**
+     * Resource type name
+     * @example "User", "Group"
+     */
+    resourceType: zod_1.z.string()
+        .optional()
+        .describe('Resource type'),
+    /**
+     * Resource creation timestamp (ISO 8601)
+     */
+    created: zod_1.z.string()
+        .datetime()
+        .optional()
+        .describe('Creation timestamp'),
+    /**
+     * Last modification timestamp (ISO 8601)
+     */
+    lastModified: zod_1.z.string()
+        .datetime()
+        .optional()
+        .describe('Last modification timestamp'),
+    /**
+     * Resource location URI
+     * Absolute URL to the resource
+     */
+    location: zod_1.z.string()
+        .url()
+        .optional()
+        .describe('Resource location URI'),
+    /**
+     * Entity tag for optimistic concurrency control
+     * Used with If-Match header for conditional updates
+     */
+    version: zod_1.z.string()
+        .optional()
+        .describe('Entity tag (ETag) for concurrency control'),
+});
+/**
+ * SCIM Name Schema
+ * Structured name components
+ */
+exports.SCIMNameSchema = zod_1.z.object({
+    /**
+     * Full name formatted for display
+     * @example "Ms. Barbara Jane Jensen III"
+     */
+    formatted: zod_1.z.string()
+        .optional()
+        .describe('Formatted full name'),
+    /**
+     * Family name (surname)
+     * @example "Jensen"
+     */
+    familyName: zod_1.z.string()
+        .optional()
+        .describe('Family name (last name)'),
+    /**
+     * Given name (first name)
+     * @example "Barbara"
+     */
+    givenName: zod_1.z.string()
+        .optional()
+        .describe('Given name (first name)'),
+    /**
+     * Middle name
+     * @example "Jane"
+     */
+    middleName: zod_1.z.string()
+        .optional()
+        .describe('Middle name'),
+    /**
+     * Honorific prefix
+     * @example "Ms.", "Dr.", "Prof."
+     */
+    honorificPrefix: zod_1.z.string()
+        .optional()
+        .describe('Honorific prefix (Mr., Ms., Dr.)'),
+    /**
+     * Honorific suffix
+     * @example "III", "Jr.", "Sr."
+     */
+    honorificSuffix: zod_1.z.string()
+        .optional()
+        .describe('Honorific suffix (Jr., Sr.)'),
+});
+/**
+ * SCIM Email Schema
+ * Multi-valued email address
+ */
+exports.SCIMEmailSchema = zod_1.z.object({
+    /**
+     * Email address value
+     */
+    value: zod_1.z.string()
+        .email()
+        .describe('Email address'),
+    /**
+     * Email type
+     * @example "work", "home", "other"
+     */
+    type: zod_1.z.enum(['work', 'home', 'other'])
+        .optional()
+        .describe('Email type'),
+    /**
+     * Display label for the email
+     */
+    display: zod_1.z.string()
+        .optional()
+        .describe('Display label'),
+    /**
+     * Whether this is the primary email
+     */
+    primary: zod_1.z.boolean()
+        .optional()
+        .default(false)
+        .describe('Primary email indicator'),
+});
+/**
+ * SCIM Phone Number Schema
+ * Multi-valued phone number
+ */
+exports.SCIMPhoneNumberSchema = zod_1.z.object({
+    /**
+     * Phone number value
+     * Format is not enforced to support international numbers
+     */
+    value: zod_1.z.string()
+        .describe('Phone number'),
+    /**
+     * Phone type
+     */
+    type: zod_1.z.enum(['work', 'home', 'mobile', 'fax', 'pager', 'other'])
+        .optional()
+        .describe('Phone number type'),
+    /**
+     * Display label for the phone number
+     */
+    display: zod_1.z.string()
+        .optional()
+        .describe('Display label'),
+    /**
+     * Whether this is the primary phone
+     */
+    primary: zod_1.z.boolean()
+        .optional()
+        .default(false)
+        .describe('Primary phone indicator'),
+});
+/**
+ * SCIM Address Schema
+ * Multi-valued physical mailing address
+ */
+exports.SCIMAddressSchema = zod_1.z.object({
+    /**
+     * Full mailing address formatted for display
+     */
+    formatted: zod_1.z.string()
+        .optional()
+        .describe('Formatted address'),
+    /**
+     * Full street address
+     */
+    streetAddress: zod_1.z.string()
+        .optional()
+        .describe('Street address'),
+    /**
+     * City or locality
+     */
+    locality: zod_1.z.string()
+        .optional()
+        .describe('City/Locality'),
+    /**
+     * State or region
+     */
+    region: zod_1.z.string()
+        .optional()
+        .describe('State/Region'),
+    /**
+     * Zip code or postal code
+     */
+    postalCode: zod_1.z.string()
+        .optional()
+        .describe('Postal code'),
+    /**
+     * Country
+     */
+    country: zod_1.z.string()
+        .optional()
+        .describe('Country'),
+    /**
+     * Address type
+     */
+    type: zod_1.z.enum(['work', 'home', 'other'])
+        .optional()
+        .describe('Address type'),
+    /**
+     * Whether this is the primary address
+     */
+    primary: zod_1.z.boolean()
+        .optional()
+        .default(false)
+        .describe('Primary address indicator'),
+});
+/**
+ * SCIM Group Reference
+ * Reference to a group the user belongs to
+ */
+exports.SCIMGroupReferenceSchema = zod_1.z.object({
+    /**
+     * Group identifier
+     */
+    value: zod_1.z.string()
+        .describe('Group ID'),
+    /**
+     * Direct reference to the group resource
+     */
+    $ref: zod_1.z.string()
+        .url()
+        .optional()
+        .describe('URI reference to the group'),
+    /**
+     * Human-readable group name
+     */
+    display: zod_1.z.string()
+        .optional()
+        .describe('Group display name'),
+    /**
+     * Type of group
+     */
+    type: zod_1.z.enum(['direct', 'indirect'])
+        .optional()
+        .describe('Membership type'),
+});
+/**
+ * SCIM Enterprise User Extension
+ * Enterprise-specific user attributes
+ */
+exports.SCIMEnterpriseUserSchema = zod_1.z.object({
+    /**
+     * Employee number
+     */
+    employeeNumber: zod_1.z.string()
+        .optional()
+        .describe('Employee number'),
+    /**
+     * Cost center
+     */
+    costCenter: zod_1.z.string()
+        .optional()
+        .describe('Cost center'),
+    /**
+     * Organization unit
+     */
+    organization: zod_1.z.string()
+        .optional()
+        .describe('Organization'),
+    /**
+     * Division
+     */
+    division: zod_1.z.string()
+        .optional()
+        .describe('Division'),
+    /**
+     * Department
+     */
+    department: zod_1.z.string()
+        .optional()
+        .describe('Department'),
+    /**
+     * Manager reference
+     */
+    manager: zod_1.z.object({
+        value: zod_1.z.string().describe('Manager ID'),
+        $ref: zod_1.z.string().url().optional().describe('Manager URI'),
+        displayName: zod_1.z.string().optional().describe('Manager name'),
+    })
+        .optional()
+        .describe('Manager reference'),
+});
+/**
+ * SCIM User Schema (Core)
+ * Complete SCIM 2.0 User resource
+ */
+exports.SCIMUserSchema = zod_1.z.object({
+    /**
+     * SCIM schema URIs
+     * Must include at minimum the core User schema URI
+     */
+    schemas: zod_1.z.array(zod_1.z.string())
+        .min(1)
+        .refine((schemas) => schemas.includes(exports.SCIM_SCHEMAS.USER), 'Must include core User schema URI')
+        .default([exports.SCIM_SCHEMAS.USER])
+        .describe('SCIM schema URIs (must include User schema)'),
+    /**
+     * Unique identifier
+     */
+    id: zod_1.z.string()
+        .optional()
+        .describe('Unique resource identifier'),
+    /**
+     * External identifier
+     * Identifier from the provisioning client
+     */
+    externalId: zod_1.z.string()
+        .optional()
+        .describe('External identifier from client system'),
+    /**
+     * Unique username
+     * REQUIRED for user creation
+     */
+    userName: zod_1.z.string()
+        .describe('Unique username (REQUIRED)'),
+    /**
+     * Structured name
+     */
+    name: exports.SCIMNameSchema
+        .optional()
+        .describe('Structured name components'),
+    /**
+     * Display name
+     */
+    displayName: zod_1.z.string()
+        .optional()
+        .describe('Display name for UI'),
+    /**
+     * Nickname or casual name
+     */
+    nickName: zod_1.z.string()
+        .optional()
+        .describe('Nickname'),
+    /**
+     * Profile URL
+     */
+    profileUrl: zod_1.z.string()
+        .url()
+        .optional()
+        .describe('Profile page URL'),
+    /**
+     * Job title
+     */
+    title: zod_1.z.string()
+        .optional()
+        .describe('Job title'),
+    /**
+     * User type (employee, contractor, etc.)
+     */
+    userType: zod_1.z.string()
+        .optional()
+        .describe('User type (employee, contractor)'),
+    /**
+     * Preferred language (ISO 639-1)
+     */
+    preferredLanguage: zod_1.z.string()
+        .optional()
+        .describe('Preferred language (ISO 639-1)'),
+    /**
+     * Locale (e.g., en-US)
+     */
+    locale: zod_1.z.string()
+        .optional()
+        .describe('Locale (e.g., en-US)'),
+    /**
+     * Timezone (e.g., America/Los_Angeles)
+     */
+    timezone: zod_1.z.string()
+        .optional()
+        .describe('Timezone'),
+    /**
+     * Account active status
+     */
+    active: zod_1.z.boolean()
+        .optional()
+        .default(true)
+        .describe('Account active status'),
+    /**
+     * Password (write-only, never returned)
+     */
+    password: zod_1.z.string()
+        .optional()
+        .describe('Password (write-only)'),
+    /**
+     * Email addresses (multi-valued)
+     */
+    emails: zod_1.z.array(exports.SCIMEmailSchema)
+        .optional()
+        .describe('Email addresses'),
+    /**
+     * Phone numbers (multi-valued)
+     */
+    phoneNumbers: zod_1.z.array(exports.SCIMPhoneNumberSchema)
+        .optional()
+        .describe('Phone numbers'),
+    /**
+     * Instant messaging addresses
+     */
+    ims: zod_1.z.array(zod_1.z.object({
+        value: zod_1.z.string(),
+        type: zod_1.z.string().optional(),
+        primary: zod_1.z.boolean().optional(),
+    }))
+        .optional()
+        .describe('IM addresses'),
+    /**
+     * Photos (profile pictures)
+     */
+    photos: zod_1.z.array(zod_1.z.object({
+        value: zod_1.z.string().url(),
+        type: zod_1.z.enum(['photo', 'thumbnail']).optional(),
+        primary: zod_1.z.boolean().optional(),
+    }))
+        .optional()
+        .describe('Photo URLs'),
+    /**
+     * Physical addresses
+     */
+    addresses: zod_1.z.array(exports.SCIMAddressSchema)
+        .optional()
+        .describe('Physical addresses'),
+    /**
+     * Group memberships
+     */
+    groups: zod_1.z.array(exports.SCIMGroupReferenceSchema)
+        .optional()
+        .describe('Group memberships'),
+    /**
+     * User entitlements
+     */
+    entitlements: zod_1.z.array(zod_1.z.object({
+        value: zod_1.z.string(),
+        type: zod_1.z.string().optional(),
+        primary: zod_1.z.boolean().optional(),
+    }))
+        .optional()
+        .describe('Entitlements'),
+    /**
+     * User roles
+     */
+    roles: zod_1.z.array(zod_1.z.object({
+        value: zod_1.z.string(),
+        type: zod_1.z.string().optional(),
+        primary: zod_1.z.boolean().optional(),
+    }))
+        .optional()
+        .describe('Roles'),
+    /**
+     * X509 certificates
+     */
+    x509Certificates: zod_1.z.array(zod_1.z.object({
+        value: zod_1.z.string(),
+        type: zod_1.z.string().optional(),
+        primary: zod_1.z.boolean().optional(),
+    }))
+        .optional()
+        .describe('X509 certificates'),
+    /**
+     * Resource metadata
+     */
+    meta: exports.SCIMMetaSchema
+        .optional()
+        .describe('Resource metadata'),
+    /**
+     * Enterprise user extension
+     * Only present when enterprise extension is used
+     */
+    [exports.SCIM_SCHEMAS.ENTERPRISE_USER]: exports.SCIMEnterpriseUserSchema
+        .optional()
+        .describe('Enterprise user attributes'),
+}).superRefine((data, ctx) => {
+    // Validate that enterprise extension schema URI is present when extension data is provided
+    const hasEnterpriseExtension = data[exports.SCIM_SCHEMAS.ENTERPRISE_USER] != null;
+    if (!hasEnterpriseExtension) {
+        return;
+    }
+    const schemas = data.schemas || [];
+    if (!schemas.includes(exports.SCIM_SCHEMAS.ENTERPRISE_USER)) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['schemas'],
+            message: `schemas must include "${exports.SCIM_SCHEMAS.ENTERPRISE_USER}" when enterprise user extension attributes are present`,
+        });
+    }
+});
+/**
+ * SCIM Member Reference
+ * Reference to a member in a group
+ */
+exports.SCIMMemberReferenceSchema = zod_1.z.object({
+    /**
+     * Member identifier
+     */
+    value: zod_1.z.string()
+        .describe('Member ID'),
+    /**
+     * Direct reference to the member resource
+     */
+    $ref: zod_1.z.string()
+        .url()
+        .optional()
+        .describe('URI reference to the member'),
+    /**
+     * Member type (User or Group for nested groups)
+     */
+    type: zod_1.z.enum(['User', 'Group'])
+        .optional()
+        .describe('Member type'),
+    /**
+     * Human-readable member name
+     */
+    display: zod_1.z.string()
+        .optional()
+        .describe('Member display name'),
+});
+/**
+ * SCIM Group Schema
+ * Complete SCIM 2.0 Group resource
+ */
+exports.SCIMGroupSchema = zod_1.z.object({
+    /**
+     * SCIM schema URIs
+     * Must include at minimum the core Group schema URI
+     */
+    schemas: zod_1.z.array(zod_1.z.string())
+        .min(1)
+        .refine((schemas) => schemas.includes(exports.SCIM_SCHEMAS.GROUP), 'Must include core Group schema URI')
+        .default([exports.SCIM_SCHEMAS.GROUP])
+        .describe('SCIM schema URIs (must include Group schema)'),
+    /**
+     * Unique identifier
+     */
+    id: zod_1.z.string()
+        .optional()
+        .describe('Unique resource identifier'),
+    /**
+     * External identifier
+     */
+    externalId: zod_1.z.string()
+        .optional()
+        .describe('External identifier from client system'),
+    /**
+     * Group display name
+     * REQUIRED for group creation
+     */
+    displayName: zod_1.z.string()
+        .describe('Group display name (REQUIRED)'),
+    /**
+     * Group members
+     */
+    members: zod_1.z.array(exports.SCIMMemberReferenceSchema)
+        .optional()
+        .describe('Group members'),
+    /**
+     * Resource metadata
+     */
+    meta: exports.SCIMMetaSchema
+        .optional()
+        .describe('Resource metadata'),
+});
+/**
+ * SCIM List Response
+ * Paginated list of resources
+ *
+ * Generic type T allows for type-safe responses when the resource type is known.
+ * For mixed resource types, use SCIMResource union.
+ */
+exports.SCIMListResponseSchema = zod_1.z.object({
+    /**
+     * SCIM schema URI
+     */
+    schemas: zod_1.z.array(zod_1.z.string())
+        .min(1)
+        .refine((schemas) => schemas.includes(exports.SCIM_SCHEMAS.LIST_RESPONSE), { message: `schemas must include ${exports.SCIM_SCHEMAS.LIST_RESPONSE}` })
+        .default([exports.SCIM_SCHEMAS.LIST_RESPONSE])
+        .describe('SCIM schema URIs'),
+    /**
+     * Total number of results matching the query
+     */
+    totalResults: zod_1.z.number()
+        .int()
+        .min(0)
+        .describe('Total results count'),
+    /**
+     * Resources returned in this response
+     * Use SCIMListResponseOf<T> for type-safe responses
+     */
+    Resources: zod_1.z.array(zod_1.z.union([exports.SCIMUserSchema, exports.SCIMGroupSchema, zod_1.z.record(zod_1.z.any())]))
+        .describe('Resources array (Users, Groups, or custom resources)'),
+    /**
+     * 1-based index of the first result
+     */
+    startIndex: zod_1.z.number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Start index (1-based)'),
+    /**
+     * Number of resources per page
+     */
+    itemsPerPage: zod_1.z.number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('Items per page'),
+});
+/**
+ * SCIM Error Response
+ * Error response format
+ */
+exports.SCIMErrorSchema = zod_1.z.object({
+    /**
+     * SCIM schema URI
+     */
+    schemas: zod_1.z.array(zod_1.z.string())
+        .min(1)
+        .refine((schemas) => schemas.includes(exports.SCIM_SCHEMAS.ERROR), { message: `schemas must include ${exports.SCIM_SCHEMAS.ERROR}` })
+        .default([exports.SCIM_SCHEMAS.ERROR])
+        .describe('SCIM schema URIs'),
+    /**
+     * HTTP status code
+     */
+    status: zod_1.z.number()
+        .int()
+        .min(400)
+        .max(599)
+        .describe('HTTP status code'),
+    /**
+     * SCIM error type
+     */
+    scimType: zod_1.z.enum([
+        'invalidFilter',
+        'tooMany',
+        'uniqueness',
+        'mutability',
+        'invalidSyntax',
+        'invalidPath',
+        'noTarget',
+        'invalidValue',
+        'invalidVers',
+        'sensitive',
+    ])
+        .optional()
+        .describe('SCIM error type'),
+    /**
+     * Human-readable error description
+     */
+    detail: zod_1.z.string()
+        .optional()
+        .describe('Error detail message'),
+});
+/**
+ * SCIM Patch Operation
+ * For PATCH requests
+ */
+exports.SCIMPatchOperationSchema = zod_1.z.object({
+    /**
+     * Operation type
+     */
+    op: zod_1.z.enum(['add', 'remove', 'replace'])
+        .describe('Operation type'),
+    /**
+     * Attribute path to modify
+     */
+    path: zod_1.z.string()
+        .optional()
+        .describe('Attribute path (optional for add)'),
+    /**
+     * Value to set
+     */
+    value: zod_1.z.any()
+        .optional()
+        .describe('Value to set'),
+});
+/**
+ * SCIM Patch Request
+ */
+exports.SCIMPatchRequestSchema = zod_1.z.object({
+    /**
+     * SCIM schema URI
+     */
+    schemas: zod_1.z.array(zod_1.z.string())
+        .min(1)
+        .refine((schemas) => schemas.includes(exports.SCIM_SCHEMAS.PATCH_OP), { message: 'SCIM PATCH requests must include the PatchOp schema URI' })
+        .default([exports.SCIM_SCHEMAS.PATCH_OP])
+        .describe('SCIM schema URIs'),
+    /**
+     * Array of patch operations
+     */
+    Operations: zod_1.z.array(exports.SCIMPatchOperationSchema)
+        .min(1)
+        .describe('Patch operations'),
+});
+/**
+ * Helper factory for creating SCIM resources
+ */
+exports.SCIM = {
+    /**
+     * Create a basic SCIM user
+     */
+    user: (userName, email, givenName, familyName) => ({
+        schemas: [exports.SCIM_SCHEMAS.USER],
+        userName,
+        emails: [{ value: email, type: 'work', primary: true }],
+        name: {
+            givenName,
+            familyName,
+        },
+        active: true,
+    }),
+    /**
+     * Create a SCIM group
+     */
+    group: (displayName, members) => ({
+        schemas: [exports.SCIM_SCHEMAS.GROUP],
+        displayName,
+        members: members || [],
+    }),
+    /**
+     * Create a list response
+     */
+    listResponse: (resources, totalResults) => ({
+        schemas: [exports.SCIM_SCHEMAS.LIST_RESPONSE],
+        totalResults: totalResults ?? resources.length,
+        Resources: resources,
+        startIndex: 1,
+        itemsPerPage: resources.length,
+    }),
+    /**
+     * Create an error response
+     */
+    error: (status, detail, scimType) => ({
+        schemas: [exports.SCIM_SCHEMAS.ERROR],
+        status,
+        detail,
+        scimType,
+    }),
+};