@edumalin/identity 3.0.0

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@edumalin/identity",
+  "version": "3.0.0",
+  "description": "Types and client for the Edumalin identity API",
+  "keywords": [
+    "Edumalin",
+    "api",
+    "identity"
+  ],
+  "author": "Edumalin <dev@edumalin.com>",
+  "contributors": [],
+  "homepage": "https://developer.edumalin.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/edumalin/edumalin.git",
+    "directory": "node/modules/identity"
+  },
+  "bugs": {
+    "url": "https://github.com/edumalin/edumalin/issues"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "node": "./dist/cjs/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./client": {
+      "types": "./dist/types/client/index.d.ts",
+      "node": "./dist/cjs/client/index.js",
+      "require": "./dist/cjs/client/index.js",
+      "default": "./dist/esm/client/index.js"
+    },
+    "./testing": {
+      "types": "./dist/types/testing/index.d.ts",
+      "node": "./dist/cjs/testing/index.js",
+      "require": "./dist/cjs/testing/index.js",
+      "default": "./dist/esm/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "client": [
+        "dist/types/client/index.d.ts"
+      ],
+      "testing": [
+        "dist/types/testing/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist/cjs/**/!(*.tsbuildinfo)",
+    "dist/esm/**/!(*.tsbuildinfo)",
+    "dist/types/**/!(*.tsbuildinfo)",
+    "src",
+    "LICENSE.md",
+    "package.json",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@edumalin/id": "3.0.0",
+    "@edumalin/platform": "3.0.0"
+  },
+  "devDependencies": {},
+  "peerDependencies": {
+    "rxjs": "^7.8.2",
+    "temporal-polyfill": "^0.3.0"
+  },
+  "optionalDependencies": {},
+  "scripts": {
+    "compile": "tsc -b ./src/tsconfig.cjs.json ./src/tsconfig.esm.json ./src/tsconfig.types.json",
+    "lint": "oxlint .",
+    "test": "vitest run",
+    "test:serve": "vitest"
+  }
+}

package/src/client/index.ts

@@ -0,0 +1 @@
+export {};

package/src/identity/identity.ts

@@ -0,0 +1,36 @@
+import { type IdentityId } from '@edumalin/id';
+import { type UrlString } from '@edumalin/platform/url';
+
+/**
+ * Identity
+ */
+export interface Identity {
+  /**
+   * Email address
+   */
+  readonly email?: string;
+  /**
+   * Gender
+   */
+  readonly gender?: 'M' | 'F';
+  /**
+   * Given name
+   */
+  readonly givenName: string;
+  /**
+   * Identity identifier
+   */
+  readonly identityId: IdentityId;
+  /**
+   * Profile picture URL
+   */
+  readonly profilePictureUrl?: UrlString;
+  /**
+   * true when the identity information is redacted
+   */
+  readonly redacted?: true;
+  /**
+   * Surname
+   */
+  readonly surname: string;
+}

package/src/identity-provider/base-identity-provider.ts

@@ -0,0 +1,32 @@
+import { type IdentityProviderId } from '@edumalin/id';
+import { type I18nString } from '@edumalin/platform/i18n';
+import { type UrlString } from '@edumalin/platform/url';
+
+import { type IdentityProviderType } from '../identity-provider-type/identity-provider-type.js';
+import { type IdentityProviderAttributeMap } from './identity-provider-attribute-map.js';
+
+/**
+ * Base identity provider
+ */
+export interface BaseIdentityProvider {
+  /**
+   * Attribute map
+   */
+  readonly attributeMap?: IdentityProviderAttributeMap;
+  /**
+   * Identity provider identifier
+   */
+  readonly identityProviderId: IdentityProviderId;
+  /**
+   * Identity provider name
+   */
+  readonly identityProviderName?: I18nString;
+  /**
+   * Identity provider type
+   */
+  readonly identityProviderType?: IdentityProviderType;
+  /**
+   * Service URL
+   */
+  readonly serviceUrl?: UrlString;
+}

package/src/identity-provider/cas-identity-provider.ts

@@ -0,0 +1,30 @@
+import { type UrlString } from '@edumalin/platform/url';
+
+import { type IdentityProviderType } from '../identity-provider-type/identity-provider-type.js';
+import { type BaseIdentityProvider } from './base-identity-provider.js';
+
+/**
+ * CAS identity provider
+ */
+export interface CasIdentityProvider extends BaseIdentityProvider {
+  /**
+   * Attribute map expression prefix
+   */
+  readonly attributeMapExpressionPrefix?: string;
+  /**
+   * Authorization URL
+   */
+  readonly authorizationUrl?: UrlString;
+  /**
+   * Identity provider type
+   */
+  readonly identityProviderType: IdentityProviderType & { readonly identityProviderTypeCode: 'cas' };
+  /**
+   * Protocol version
+   */
+  readonly protocolVersion: '2.0' | '3.0';
+  /**
+   * Validation service URL
+   */
+  readonly validationServiceUrl?: UrlString;
+}

package/src/identity-provider/identity-provider-attribute-map-mapping.ts

@@ -0,0 +1,30 @@
+/**
+ * Identity provider attribute map mapping
+ */
+export type IdentityProviderAttributeMapMapping =
+  | {
+      /**
+       * Constant
+       */
+      readonly constant: string;
+      /**
+       * Mapping type
+       */
+      readonly mappingType: 'constant';
+    }
+  | {
+      /**
+       * mapping type
+       */
+      readonly mappingType: 'disabled';
+    }
+  | {
+      /**
+       * Mapping type
+       */
+      readonly mappingType: 'path';
+      /**
+       * Path
+       */
+      readonly path: string;
+    };

package/src/identity-provider/identity-provider-attribute-map.ts

@@ -0,0 +1,61 @@
+import { type IdentityProviderAttributeMapMapping } from './identity-provider-attribute-map-mapping.js';
+
+/**
+ * Identity provider attribute map
+ *
+ * Provides a mapping mechanism for each identity attribute
+ */
+export interface IdentityProviderAttributeMap {
+  /**
+   * Class names
+   */
+  readonly classNames?: IdentityProviderAttributeMapMapping;
+  /**
+   * Email address
+   */
+  readonly email?: IdentityProviderAttributeMapMapping;
+  /**
+   * Establishment code
+   */
+  readonly establishmentCode?: IdentityProviderAttributeMapMapping;
+  /**
+   * Establishment identifier
+   */
+  readonly establishmentId?: IdentityProviderAttributeMapMapping;
+  /**
+   * External user identifier
+   */
+  readonly externalUserId?: IdentityProviderAttributeMapMapping;
+  /**
+   * Given name
+   */
+  readonly givenName?: IdentityProviderAttributeMapMapping;
+  /**
+   * Group names
+   */
+  readonly groupNames?: IdentityProviderAttributeMapMapping;
+  /**
+   * Identity name (given name and surname as a single value)
+   */
+  readonly identityName?: IdentityProviderAttributeMapMapping;
+  /**
+   * Whether the user is a headmaster
+   */
+  readonly isHeadmaster?: IdentityProviderAttributeMapMapping;
+  /**
+   * Whether the user is a parent
+   */
+  readonly isParent?: IdentityProviderAttributeMapMapping;
+  /**
+   * Whether the user is a student
+   */
+  readonly isStudent?: IdentityProviderAttributeMapMapping;
+  /**
+   * Whether the user is a teacher
+   */
+  readonly isTeacher?: IdentityProviderAttributeMapMapping;
+  /**
+   * Surname
+   */
+  readonly surname?: IdentityProviderAttributeMapMapping;
+}

package/src/identity-provider/identity-provider.ts

@@ -0,0 +1,13 @@
+import { type CasIdentityProvider } from './cas-identity-provider.js';
+import { type OidcIdentityProvider } from './oidc-identity-provider.js';
+import { type PlatformIdentityProvider } from './platform-identity-provider.js';
+import { type SamlIdentityProvider } from './saml-identity-provider.js';
+
+/**
+ * Identity provider
+ */
+export type IdentityProvider =
+  | CasIdentityProvider
+  | OidcIdentityProvider
+  | PlatformIdentityProvider
+  | SamlIdentityProvider;

package/src/identity-provider/oidc-identity-provider.ts

@@ -0,0 +1,28 @@
+import { type IdentityProviderType } from '../identity-provider-type/identity-provider-type.js';
+import { type BaseIdentityProvider } from './base-identity-provider.js';
+
+/**
+ * OpenID Connect identity provider
+ */
+export interface OidcIdentityProvider extends BaseIdentityProvider {
+  /**
+   * Challenge algorithm
+   */
+  readonly challengeAlgorithm: 'SHA-256';
+  /**
+   * Challenge method
+   */
+  readonly challengeMethod: 'S256';
+  /**
+   * Client identifier
+   */
+  readonly clientId: string;
+  /**
+   * Client secret
+   */
+  readonly clientSecret: string;
+  /**
+   * Identity provider type
+   */
+  readonly identityProviderType: IdentityProviderType & { readonly identityProviderTypeCode: 'oidc' };
+}

package/src/identity-provider/platform-identity-provider.ts

@@ -0,0 +1,12 @@
+import { type IdentityProviderType } from '../identity-provider-type/identity-provider-type.js';
+import { type BaseIdentityProvider } from './base-identity-provider.js';
+
+/**
+ * Platform identity provider
+ */
+export interface PlatformIdentityProvider extends BaseIdentityProvider {
+  /**
+   * Identity provider type
+   */
+  readonly identityProviderType: IdentityProviderType & { readonly identityProviderTypeCode: 'platform' };
+}

package/src/identity-provider/saml-identity-provider.ts

@@ -0,0 +1,12 @@
+import { type IdentityProviderType } from '../identity-provider-type/identity-provider-type.js';
+import { type BaseIdentityProvider } from './base-identity-provider.js';
+
+/**
+ * SAML identity provider
+ */
+export interface SamlIdentityProvider extends BaseIdentityProvider {
+  /**
+   * Identity provider type
+   */
+  readonly identityProviderType: IdentityProviderType & { readonly identityProviderTypeCode: 'saml' };
+}

package/src/identity-provider-type/identity-provider-type.ts

@@ -0,0 +1,16 @@
+import { type IdentityProviderTypeCode } from '@edumalin/id';
+import { type I18nString } from '@edumalin/platform/i18n';
+
+/**
+ * Identity provider type
+ */
+export interface IdentityProviderType {
+  /**
+   * Identity provider type code
+   */
+  readonly identityProviderTypeCode: IdentityProviderTypeCode;
+  /**
+   * Identity provider type name
+   */
+  readonly identityProviderTypeName?: I18nString;
+}

package/src/identity.domain.ts

@@ -0,0 +1,6 @@
+import { createDomain } from '@edumalin/platform/domain';
+
+/**
+ * Identity domain
+ */
+export const identityDomain = createDomain('@edumalin/identity');

package/src/identity.error.ts

@@ -0,0 +1,8 @@
+import { createErrorType } from '@edumalin/platform/error';
+
+import { identityDomain } from './identity.domain.js';
+
+/**
+ * Identity error
+ */
+export const identityError = createErrorType(identityDomain, {});

package/src/index.ts

@@ -0,0 +1,12 @@
+export { type BaseIdentityProvider } from './identity-provider/base-identity-provider.js';
+export { type CasIdentityProvider } from './identity-provider/cas-identity-provider.js';
+export { type Identity } from './identity/identity.js';
+export { identityDomain } from './identity.domain.js';
+export { identityError } from './identity.error.js';
+export { type IdentityProvider } from './identity-provider/identity-provider.js';
+export { type IdentityProviderAttributeMap } from './identity-provider/identity-provider-attribute-map.js';
+export { type IdentityProviderAttributeMapMapping } from './identity-provider/identity-provider-attribute-map-mapping.js';
+export { type IdentityProviderType } from './identity-provider-type/identity-provider-type.js';
+export { type OidcIdentityProvider } from './identity-provider/oidc-identity-provider.js';
+export { type PlatformIdentityProvider } from './identity-provider/platform-identity-provider.js';
+export { type SamlIdentityProvider } from './identity-provider/saml-identity-provider.js';

package/src/testing/create-test-base-identity-provider.ts

@@ -0,0 +1,32 @@
+import { generateIdentityProviderId } from '@edumalin/id';
+import { type BaseIdentityProvider } from '@edumalin/identity';
+import { type DeepPartial } from '@edumalin/platform/typescript';
+import { asUrlString } from '@edumalin/platform/url';
+
+import { createTestIdentityProviderAttributeMap } from './create-test-identity-provider-attribute-map.js';
+
+/**
+ * Creates a test base identity provider
+ *
+ * @param identityProvider Base base identity provider properties
+ * @returns Test base identity provider
+ */
+export function createTestBaseIdentityProvider(
+  identityProvider?: DeepPartial<BaseIdentityProvider>
+): BaseIdentityProvider {
+  const attributeMap = createTestIdentityProviderAttributeMap(identityProvider?.attributeMap);
+  const identityProviderId = identityProvider?.identityProviderId ?? generateIdentityProviderId();
+  const identityProviderName = identityProvider?.identityProviderName ?? {
+    'en-US': 'Test identity provider',
+    'fr-FR': "Fournisseur d'identité de test",
+  };
+  const serviceUrl =
+    identityProvider?.serviceUrl ?? asUrlString('https://developer.edumalin.com/test/identity/provider');
+
+  return {
+    attributeMap,
+    identityProviderId,
+    identityProviderName,
+    serviceUrl,
+  };
+}

package/src/testing/create-test-cas-identity-provider.ts

@@ -0,0 +1,33 @@
+import { type CasIdentityProvider } from '@edumalin/identity';
+import { type DeepPartial } from '@edumalin/platform/typescript';
+import { asUrlString } from '@edumalin/platform/url';
+
+import { createTestBaseIdentityProvider } from './create-test-base-identity-provider.js';
+import { createTestIdentityProviderType } from './create-test-identity-provider-type.js';
+
+/**
+ * Creates a test CAS identity provider
+ *
+ * @param identityProvider Base CAS identity provider properties
+ * @returns Test CAS identity provider
+ */
+export function createTestCasIdentityProvider(
+  identityProvider?: DeepPartial<CasIdentityProvider>
+): CasIdentityProvider {
+  const attributeMapExpressionPrefix = '/cas:serviceResponse/cas:authenticationSuccess/';
+  const identityProviderType = {
+    ...createTestIdentityProviderType(identityProvider?.identityProviderType),
+    identityProviderTypeCode: 'cas' as const,
+  };
+  const protocolVersion = identityProvider?.protocolVersion ?? '3.0';
+  const validationServiceUrl =
+    identityProvider?.validationServiceUrl ?? asUrlString('https://developer.edumalin.com/cas/validationService');
+
+  return {
+    ...createTestBaseIdentityProvider(identityProvider as never),
+    attributeMapExpressionPrefix,
+    identityProviderType,
+    protocolVersion,
+    validationServiceUrl,
+  };
+}

package/src/testing/create-test-identity-provider-attribute-map-mapping.ts

@@ -0,0 +1,18 @@
+import { type IdentityProviderAttributeMapMapping } from '@edumalin/identity';
+import { type DeepPartial } from '@edumalin/platform/typescript';
+
+/**
+ * Creates a test identity provider attribute map mapping
+ *
+ * @param attributeMapMapping Base identity provider attribute map mapping properties
+ * @returns Test identity provider attribute map mapping
+ */
+export function createTestIdentityProviderAttributeMapMapping(
+  _attributeMapMapping?: DeepPartial<IdentityProviderAttributeMapMapping>
+): IdentityProviderAttributeMapMapping {
+  // TODO
+
+  return {
+    mappingType: 'disabled',
+  };
+}

package/src/testing/create-test-identity-provider-attribute-map.ts

@@ -0,0 +1,40 @@
+import { type IdentityProviderAttributeMap } from '@edumalin/identity';
+import { type DeepPartial } from '@edumalin/platform/typescript';
+
+import { createTestIdentityProviderAttributeMapMapping } from './create-test-identity-provider-attribute-map-mapping';
+
+/**
+ * Creates a test identity provider attribute map
+ *
+ * @param attributeMap Base identity provider attribute map properties
+ * @returns Test identity provider attribute map
+ */
+export function createTestIdentityProviderAttributeMap(
+  attributeMap?: DeepPartial<IdentityProviderAttributeMap>
+): IdentityProviderAttributeMap {
+  const classNames = createTestIdentityProviderAttributeMapMapping(attributeMap?.classNames);
+  const establishmentCode = createTestIdentityProviderAttributeMapMapping(attributeMap?.establishmentCode);
+  const externalUserId = createTestIdentityProviderAttributeMapMapping(attributeMap?.externalUserId);
+  const givenName = createTestIdentityProviderAttributeMapMapping(attributeMap?.givenName);
+  const groupNames = createTestIdentityProviderAttributeMapMapping(attributeMap?.groupNames);
+  const identityName = createTestIdentityProviderAttributeMapMapping(attributeMap?.identityName);
+  const isHeadmaster = createTestIdentityProviderAttributeMapMapping(attributeMap?.isHeadmaster);
+  const isParent = createTestIdentityProviderAttributeMapMapping(attributeMap?.isParent);
+  const isStudent = createTestIdentityProviderAttributeMapMapping(attributeMap?.isStudent);
+  const isTeacher = createTestIdentityProviderAttributeMapMapping(attributeMap?.isTeacher);
+  const surname = createTestIdentityProviderAttributeMapMapping(attributeMap?.surname);
+
+  return {
+    classNames,
+    establishmentCode,
+    externalUserId,
+    givenName,
+    groupNames,
+    identityName,
+    isHeadmaster,
+    isParent,
+    isStudent,
+    isTeacher,
+    surname,
+  };
+}

package/src/testing/create-test-identity-provider-type.ts

@@ -0,0 +1,25 @@
+import { identityProviderTypeCodes } from '@edumalin/id';
+import { type IdentityProviderType } from '@edumalin/identity';
+import { getRandomArrayValue } from '@edumalin/platform/random';
+import { type DeepPartial } from '@edumalin/platform/typescript';
+
+/**
+ * Creates a test identity provider type
+ *
+ * @param identityProviderType Base identity provider type properties
+ * @returns Test identity provider type
+ */
+export function createTestIdentityProviderType(
+  identityProviderType?: DeepPartial<IdentityProviderType>
+): IdentityProviderType {
+  const identityProviderTypeCode = getRandomArrayValue(identityProviderTypeCodes);
+  const identityProviderTypeName = identityProviderType?.identityProviderTypeName ?? {
+    'en-US': `${identityProviderTypeCode} test identity provider type`,
+    'fr-FR': `Type de fournisseur d'identité de test ${identityProviderTypeCode}`,
+  };
+
+  return {
+    identityProviderTypeCode,
+    identityProviderTypeName,
+  };
+}

package/src/testing/create-test-identity-provider.ts

@@ -0,0 +1,38 @@
+import {
+  type CasIdentityProvider,
+  type IdentityProvider,
+  type OidcIdentityProvider,
+  type PlatformIdentityProvider,
+  type SamlIdentityProvider,
+} from '@edumalin/identity';
+import { getRandomArrayValue } from '@edumalin/platform/random';
+import { type DeepPartial } from '@edumalin/platform/typescript';
+
+import { createTestCasIdentityProvider } from './create-test-cas-identity-provider.js';
+import { createTestPlatformIdentityProvider } from './create-test-platform-identity-provider.js';
+import { createTestOidcIdentityProvider } from './create-test-oidc-identity-provider.js';
+import { createTestSamlIdentityProvider } from './create-test-saml-identity-provider.js';
+
+/**
+ * Creates a test identity provider
+ *
+ * @param identityProvider Base identity provider properties
+ * @returns Identity provider
+ */
+export function createTestIdentityProvider(identityProvider?: DeepPartial<IdentityProvider>): IdentityProvider {
+  const identityProviderType =
+    identityProvider?.identityProviderType?.identityProviderTypeCode ??
+    getRandomArrayValue(['cas', 'platform', 'oidc', 'saml']);
+  switch (identityProviderType) {
+    case 'cas':
+      return createTestCasIdentityProvider(identityProvider as DeepPartial<CasIdentityProvider> | undefined);
+    case 'oidc':
+      return createTestOidcIdentityProvider(identityProvider as DeepPartial<OidcIdentityProvider> | undefined);
+    case 'platform':
+      return createTestPlatformIdentityProvider(identityProvider as DeepPartial<PlatformIdentityProvider> | undefined);
+    case 'saml':
+      return createTestSamlIdentityProvider(identityProvider as DeepPartial<SamlIdentityProvider> | undefined);
+    default:
+      throw new Error(`unknown identity provider type`);
+  }
+}

package/src/testing/create-test-identity.ts

@@ -0,0 +1,30 @@
+import { generateIdentityId } from '@edumalin/id';
+import { type Identity } from '@edumalin/identity';
+import { type DeepPartial } from '@edumalin/platform/typescript';
+import { asUrlString } from '@edumalin/platform/url';
+
+/**
+ * Creates a test identity
+ *
+ * @param identity Base identity properties
+ * @returns Test identity
+ */
+export function createTestIdentity(identity?: DeepPartial<Identity>): Identity {
+  const email = identity?.email;
+  const givenName = identity?.givenName ?? 'Camille';
+  const identityId = identity?.identityId ?? generateIdentityId();
+  const profilePictureUrl =
+    identity?.profilePictureUrl ??
+    asUrlString(
+      'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAA2UlEQVR4nOzRoWpCcRiG8W38+2CXsA22Wxi7iKWlExcHYzcxBoZj0AsQu9Gs6Vi8AY1iMwgaDKJ4DW96PPD88vuFh6/MX0Y3ifv3KtpPZ9/RfrN9jvZ30foKGUAzgGYAzQCaATQDaAbQyno3jg7OvSbad1/70X5w+oz2rf+AATQDaAbQDKAZQDOAZgCt/D0uo4PbziLaV/Ux2v/8PkT71n/AAJoBNANoBtAMoBlAM4BWnj6G0cGq+Y/29ds+2n9NDtG+9R8wgGYAzQCaATQDaAbQDKBdAgAA//+JQhusQ+q2ywAAAABJRU5ErkJggg'
+    );
+  const surname = identity?.surname ?? 'Dupont';
+
+  return {
+    ...(email ? { email } : {}),
+    givenName,
+    identityId,
+    ...(profilePictureUrl ? { profilePictureUrl } : {}),
+    surname,
+  };
+}

package/src/testing/create-test-oidc-identity-provider.ts

@@ -0,0 +1,33 @@
+import { type OidcIdentityProvider } from '@edumalin/identity';
+import { type DeepPartial } from '@edumalin/platform/typescript';
+
+import { createTestBaseIdentityProvider } from './create-test-base-identity-provider.js';
+import { createTestIdentityProviderType } from './create-test-identity-provider-type.js';
+
+/**
+ * Creates a test OpenID Connect identity provider
+ *
+ * @param identityProvider Base OpenID Connect identity provider properties
+ * @returns Test OpenID Connect identity provider
+ */
+export function createTestOidcIdentityProvider(
+  identityProvider?: DeepPartial<OidcIdentityProvider>
+): OidcIdentityProvider {
+  const challengeAlgorithm = identityProvider?.challengeAlgorithm ?? 'SHA-256';
+  const challengeMethod = identityProvider?.challengeMethod ?? 'S256';
+  const clientId = identityProvider?.clientId ?? 'test-client-id';
+  const clientSecret = identityProvider?.clientSecret ?? 'test-client-secret';
+  const identityProviderType = {
+    ...createTestIdentityProviderType(identityProvider?.identityProviderType),
+    identityProviderTypeCode: 'oidc' as const,
+  };
+
+  return {
+    ...createTestBaseIdentityProvider(identityProvider as never),
+    challengeAlgorithm,
+    challengeMethod,
+    clientId,
+    clientSecret,
+    identityProviderType,
+  };
+}