@enterprisestandard/esv 0.0.5-beta.20260114.1

package/README.md

@@ -0,0 +1,203 @@
+# Enterprise Standard Validator
+
+The set of validators used to validate that an application correctly implements Enterprise Standards.
+
+This package provides comprehensive validation tests for:
+
+- **SSO (Single Sign-On)**: Validates OIDC login flows, session management, and logout
+- **IAM (Identity and Access Management)**: Validates SCIM user and group provisioning
+- **Workload Identity**: Validates service-to-service authentication
+
+## Installation
+
+```bash
+bun add @enterprisestandard/esv vitest
+```
+
+## Usage
+
+### With Vitest (Recommended)
+
+Create a test file in your project (e.g., `tests/esv.test.ts`):
+
+```typescript
+import { describe, it } from 'vitest';
+import { createSSOTests, createWorkloadTests } from '@enterprisestandard/esv';
+
+const BASE_URL = process.env.TEST_BASE_URL || 'http://localhost:3000';
+
+describe('Enterprise Standard Validation', () => {
+  describe('SSO', () => {
+    const tests = createSSOTests({ baseUrl: BASE_URL });
+    tests.map(({name, fn}) => it(name, fn))
+  });
+
+  describe('Workload', () => {
+    const tests = createWorkloadTests({ baseUrl: BASE_URL });
+    tests.map(({name, fn}) => it(name, fn))
+  });
+});
+```
+
+Run with:
+```bash
+bun run vitest run
+```
+
+### Programmatic Usage
+
+```typescript
+import { validateAll, printReport } from '@enterprisestandard/esv';
+
+async function runValidation() {
+  const report = await validateAll({
+    baseUrl: 'http://localhost:3000',
+    sso: {
+      loginPath: '/api/auth/login',
+      userPath: '/api/auth/user',
+    },
+    workload: {
+      tokenPath: '/api/workload/token',
+    },
+  });
+
+  printReport(report);
+  
+  if (!report.passed) {
+    process.exit(1);
+  }
+}
+
+runValidation();
+```
+
+**Handler configuration precedence:** Enterprise Standard handlers merge defaults provided at `enterpriseStandard` initialization with per-call overrides (per-call wins). Ensure your app exposes the tested routes (`/api/auth/*`, `/api/workload/*`, etc.) with either init-time defaults or per-call overrides matching the paths used in these tests.
+
+## Configuration
+
+### SSO Validation Config
+
+```typescript
+interface SSOValidationConfig {
+  baseUrl: string;
+  loginPath?: string;           // Default: '/api/auth/login'
+  callbackPath?: string;        // Default: '/api/auth/callback'
+  userPath?: string;            // Default: '/api/auth/user'
+  logoutPath?: string;          // Default: '/api/auth/logout'
+  backChannelLogoutPath?: string; // Default: '/api/auth/logout/backchannel'
+  tokenPath?: string;           // Default: '/api/auth/token'
+  refreshPath?: string;         // Default: '/api/auth/refresh'
+  timeout?: number;             // Default: 5000ms
+  expectedAuthorizationUrlPattern?: RegExp;
+}
+```
+
+### IAM Validation Config
+
+```typescript
+interface IAMValidationConfig {
+  baseUrl: string;
+  scimPath?: string;            // Default: '/api/iam'
+  bearerToken?: string;         // Required: Bearer token for SCIM API
+  getToken?: () => Promise<string>; // Alternative: Function to get token
+  testUser?: {
+    userName: string;
+    displayName: string;
+    emails: Array<{ value: string; primary?: boolean }>;
+    name?: { givenName?: string; familyName?: string };
+  };
+  testGroup?: {
+    displayName: string;
+    externalId?: string;
+  };
+  timeout?: number;
+}
+```
+
+### Workload Validation Config
+
+```typescript
+interface WorkloadValidationConfig {
+  baseUrl: string;
+  tokenPath?: string;           // Default: '/api/workload/token'
+  validatePath?: string;        // Default: '/api/workload/validate'
+  jwksPath?: string;            // Default: '/api/workload/jwks'
+  refreshPath?: string;         // Default: '/api/workload/refresh'
+  testScopes?: string;
+  validToken?: string;          // Optional: Pre-acquired valid token
+  timeout?: number;
+}
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Enterprise Standard Validation
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      
+      - name: Install dependencies
+        run: bun install
+      
+      - name: Start application
+        run: bun run dev &
+        
+      - name: Wait for app to be ready
+        run: |
+          timeout 30 bash -c 'until curl -s http://localhost:3000 > /dev/null; do sleep 1; done'
+      
+      - name: Run ESV tests
+        run: bun run vitest run tests/esv.test.ts
+```
+
+## Test Coverage
+
+### SSO Tests
+
+| Test | Description |
+|------|-------------|
+| Login Endpoint | Verifies redirect to IdP with PKCE parameters |
+| User Endpoint (Unauth) | Verifies 401 response without session |
+| Logout Endpoint | Verifies cookie clearing |
+| Back-Channel Logout | Verifies endpoint exists and handles requests |
+| Callback Invalid | Verifies error handling for invalid callbacks |
+| Token Endpoint (Unauth) | Verifies 401 response without session |
+| Refresh Endpoint (Unauth) | Verifies 401 response without session |
+
+### IAM Tests
+
+| Test | Description |
+|------|-------------|
+| Authentication Required | Verifies SCIM endpoints require auth |
+| Users Schema | Verifies SCIM ListResponse structure |
+| Groups Schema | Verifies SCIM ListResponse structure |
+| Create User | Creates a test user via SCIM |
+| Get User | Retrieves created user by ID |
+| Update User | Patches user attributes |
+| Delete User | Deletes user and verifies 404 |
+| Create Group | Creates a test group via SCIM |
+| Delete Group | Deletes group |
+
+### Workload Tests
+
+| Test | Description |
+|------|-------------|
+| JWKS Endpoint | Verifies JWKS structure with keys |
+| Token Endpoint | Acquires workload access token |
+| Validate No Auth | Verifies 401 without auth header |
+| Validate Invalid | Verifies rejection of invalid tokens |
+| Validate Valid | Verifies acceptance of valid tokens |
+| Whoami with Workload | Verifies workload identity in response |
+| Refresh Endpoint | Verifies token refresh works |
+
+## License
+
+Proprietary - Enterprise Standard

package/dist/iam/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * IAM Validation Tests
+ *
+ * These tests validate that an application correctly implements
+ * Enterprise Standard IAM (Identity and Access Management) via SCIM.
+ *
+ * The core IAM tests validate user management operations. Group management
+ * has two optional extensions:
+ * - `ext.createGroupsOutboundTests()` - Tests app calling external IAM provider
+ * - `ext.createGroupsInboundTests()` - Tests external IAM provider calling app
+ */
+import type { IAMValidationConfig, TestDef, ValidationSuiteResult } from '../types';
+/**
+ * Runs all IAM validation tests (core user tests + optional groups tests)
+ */
+export declare function validateIAM(config: IAMValidationConfig): Promise<ValidationSuiteResult>;
+/**
+ * Creates Vitest-compatible test suite for IAM validation.
+ *
+ * Returns `{ tests, ext }` where:
+ * - `tests`: Core user management tests (always run)
+ * - `ext`: Extension methods for optional functionality:
+ *   - `createGroupsOutboundTests()` - Tests app calling external IAM provider
+ *   - `createGroupsInboundTests()` - Tests external IAM provider calling app
+ *
+ * @example
+ * ```ts
+ * describe('IAM', () => {
+ *   const { tests, ext } = createIAMTests({ ... });
+ *
+ *   // Core user tests
+ *   tests.forEach(({ name, fn }) => it(name, fn));
+ *
+ *   // Optional: Groups Outbound tests (app -> external IAM)
+ *   describe('Groups Outbound', () => {
+ *     ext.createGroupsOutboundTests().forEach(({ name, fn }) => it(name, fn));
+ *   });
+ *
+ *   // Optional: Groups Inbound tests (external IAM -> app)
+ *   describe('Groups Inbound', () => {
+ *     ext.createGroupsInboundTests().forEach(({ name, fn }) => it(name, fn));
+ *   });
+ * });
+ * ```
+ */
+export declare function createIAMTests(config: IAMValidationConfig): {
+    tests: TestDef[];
+    ext: {
+        /**
+         * Create tests for Groups Outbound extension.
+         * Tests app calling external IAM provider to create/manage groups.
+         * These tests hit the external IAM's SCIM endpoints (proxied through the app).
+         */
+        createGroupsOutboundTests: () => Array<TestDef>;
+        /**
+         * Create tests for Groups Inbound extension.
+         * Tests external IAM provider calling app's SCIM endpoints.
+         * These tests simulate an external IAM provider (like SailPoint) pushing group changes to the app.
+         */
+        createGroupsInboundTests: () => Array<TestDef>;
+    };
+};
+export type { IAMValidationConfig };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/iam/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAoB,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAqftG;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAoG7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB;;;QA6DtD;;;;WAIG;yCAC4B,KAAK,CAAC,OAAO,CAAC;QAmB7C;;;;WAIG;wCAC2B,KAAK,CAAC,OAAO,CAAC;;EAgG/C;AAED,YAAY,EAAE,mBAAmB,EAAE,CAAC"}