@codemation/host 0.0.1

package/src/domain/credentials/CredentialServices.ts

@@ -0,0 +1,145 @@
+import type {
+  CredentialBinding,
+  CredentialBindingKey,
+  CredentialHealth,
+  CredentialInstanceId,
+  CredentialInstanceRecord as CoreCredentialInstanceRecord,
+  CredentialJsonRecord,
+  CredentialSessionService,
+  CredentialHealthTester as CoreCredentialHealthTester,
+  CredentialSessionFactory as CoreCredentialSessionFactory,
+  CredentialSessionFactoryArgs,
+  AnyCredentialType,
+  CredentialType as CoreCredentialType,
+} from "@codemation/core";
+
+export type JsonRecord = CredentialJsonRecord;
+
+export type CredentialSecretRef = Readonly<
+  | { kind: "db" }
+  | {
+      kind: "env";
+      envByField: Readonly<Record<string, string>>;
+    }
+  | {
+      kind: "code";
+      value: JsonRecord;
+    }
+>;
+
+/**
+ * Persisted credential instance for the host store (stricter `CredentialSecretRef` than core's envelope).
+ */
+export type CredentialInstanceRecord<TPublicConfig extends JsonRecord = JsonRecord> = Readonly<
+  Omit<CoreCredentialInstanceRecord<TPublicConfig>, "secretRef"> & { secretRef: CredentialSecretRef }
+>;
+
+export type CredentialSecretMaterialRecord = Readonly<{
+  instanceId: CredentialInstanceId;
+  encryptedJson: string;
+  encryptionKeyId: string;
+  schemaVersion: number;
+  updatedAt: string;
+}>;
+
+export type CredentialOAuth2MaterialMetadata = Readonly<{
+  providerId: string;
+  connectedEmail?: string;
+  connectedAt?: string;
+  scopes: ReadonlyArray<string>;
+  updatedAt: string;
+}>;
+
+export type CredentialOAuth2MaterialRecord = Readonly<
+  {
+    instanceId: CredentialInstanceId;
+  } & CredentialSecretMaterialRecord &
+    CredentialOAuth2MaterialMetadata
+>;
+
+export type CredentialOAuth2StateRecord = Readonly<{
+  state: string;
+  instanceId: CredentialInstanceId;
+  codeVerifier?: string;
+  providerId?: string;
+  requestedScopes: ReadonlyArray<string>;
+  createdAt: string;
+  expiresAt: string;
+}>;
+
+export type CredentialTestRecord = Readonly<{
+  testId: string;
+  instanceId: CredentialInstanceId;
+  health: CredentialHealth;
+  testedAt: string;
+  expiresAt?: string;
+}>;
+
+export interface CredentialStore {
+  listInstances(): Promise<ReadonlyArray<CredentialInstanceRecord>>;
+  getInstance(instanceId: CredentialInstanceId): Promise<CredentialInstanceRecord | undefined>;
+  saveInstance(
+    args: Readonly<{
+      instance: CredentialInstanceRecord;
+      secretMaterial?: CredentialSecretMaterialRecord;
+    }>,
+  ): Promise<void>;
+  deleteInstance(instanceId: CredentialInstanceId): Promise<void>;
+  getSecretMaterial(instanceId: CredentialInstanceId): Promise<CredentialSecretMaterialRecord | undefined>;
+  createOAuth2State(record: CredentialOAuth2StateRecord): Promise<void>;
+  consumeOAuth2State(state: string): Promise<CredentialOAuth2StateRecord | undefined>;
+  getOAuth2Material(instanceId: CredentialInstanceId): Promise<CredentialOAuth2MaterialRecord | undefined>;
+  saveOAuth2Material(
+    args: Readonly<{
+      instanceId: CredentialInstanceId;
+      encryptedJson: string;
+      encryptionKeyId: string;
+      schemaVersion: number;
+      metadata: CredentialOAuth2MaterialMetadata;
+    }>,
+  ): Promise<void>;
+  deleteOAuth2Material(instanceId: CredentialInstanceId): Promise<void>;
+  upsertBinding(binding: CredentialBinding): Promise<void>;
+  getBinding(key: CredentialBindingKey): Promise<CredentialBinding | undefined>;
+  listBindingsByWorkflowId(workflowId: string): Promise<ReadonlyArray<CredentialBinding>>;
+  saveTestResult(record: CredentialTestRecord): Promise<void>;
+  getLatestTestResult(instanceId: CredentialInstanceId): Promise<CredentialTestRecord | undefined>;
+  getLatestTestResults(
+    instanceIds: ReadonlyArray<CredentialInstanceId>,
+  ): Promise<ReadonlyMap<CredentialInstanceId, CredentialTestRecord>>;
+}
+
+export type CredentialSessionFactory<
+  TPublicConfig extends JsonRecord = JsonRecord,
+  TMaterial extends JsonRecord = JsonRecord,
+  TSession = unknown,
+> = CoreCredentialSessionFactory<TPublicConfig, TMaterial, TSession>;
+
+export type CredentialHealthTester<
+  TPublicConfig extends JsonRecord = JsonRecord,
+  TMaterial extends JsonRecord = JsonRecord,
+> = CoreCredentialHealthTester<TPublicConfig, TMaterial>;
+
+export type CredentialType<
+  TPublicConfig extends JsonRecord = JsonRecord,
+  TMaterial extends JsonRecord = JsonRecord,
+  TSession = unknown,
+> = CoreCredentialType<TPublicConfig, TMaterial, TSession>;
+
+export type { AnyCredentialType, CredentialSessionFactoryArgs };
+
+export type MutableCredentialSessionService = CredentialSessionService &
+  Readonly<{
+    evictInstance(instanceId: CredentialInstanceId): void;
+    evictBinding(bindingKey: CredentialBindingKey): void;
+  }>;
+
+export { CredentialTypeRegistryImpl } from "./CredentialTypeRegistryImpl";
+export { CredentialBindingService } from "./CredentialBindingService";
+export { CredentialInstanceService } from "./CredentialInstanceService";
+export { CredentialMaterialResolver } from "./CredentialMaterialResolver";
+export { CredentialRuntimeMaterialService } from "./CredentialRuntimeMaterialService";
+export { CredentialFieldEnvOverlayService } from "./CredentialFieldEnvOverlayService";
+export { CredentialSecretCipher } from "./CredentialSecretCipher";
+export { CredentialSessionServiceImpl } from "./CredentialSessionServiceImpl";
+export { CredentialTestService } from "./CredentialTestService";

package/src/domain/credentials/CredentialSessionServiceImpl.ts

@@ -0,0 +1,119 @@
+import type {
+  CredentialBindingKey,
+  CredentialInstanceId,
+  CredentialSessionService,
+  WorkflowRepository,
+} from "@codemation/core";
+
+import { CoreTokens, CredentialUnboundError, inject, injectable } from "@codemation/core";
+
+import { ApplicationRequestError } from "../../application/ApplicationRequestError";
+
+import { ApplicationTokens } from "../../applicationTokens";
+
+import { WorkflowCredentialNodeResolver } from "./WorkflowCredentialNodeResolver";
+import { CredentialFieldEnvOverlayService } from "./CredentialFieldEnvOverlayService";
+import { CredentialRuntimeMaterialService } from "./CredentialRuntimeMaterialService";
+import type { CredentialStore } from "./CredentialServices";
+import { CredentialTypeRegistryImpl } from "./CredentialServices";
+
+@injectable()
+export class CredentialSessionServiceImpl implements CredentialSessionService {
+  private readonly cachedSessionsByInstanceId = new Map<CredentialInstanceId, Promise<unknown>>();
+  private readonly cachedInstanceIdsByBindingKey = new Map<string, CredentialInstanceId>();
+
+  constructor(
+    @inject(ApplicationTokens.CredentialStore)
+    private readonly credentialStore: CredentialStore,
+    @inject(CredentialRuntimeMaterialService)
+    private readonly credentialRuntimeMaterialService: CredentialRuntimeMaterialService,
+    @inject(CredentialFieldEnvOverlayService)
+    private readonly credentialFieldEnvOverlayService: CredentialFieldEnvOverlayService,
+    @inject(CredentialTypeRegistryImpl)
+    private readonly credentialTypeRegistry: CredentialTypeRegistryImpl,
+    @inject(CoreTokens.WorkflowRepository)
+    private readonly workflowRepository: WorkflowRepository,
+    @inject(WorkflowCredentialNodeResolver)
+    private readonly workflowCredentialNodeResolver: WorkflowCredentialNodeResolver,
+  ) {}
+
+  async getSession<TSession = unknown>(
+    args: Readonly<{ workflowId: string; nodeId: string; slotKey: string }>,
+  ): Promise<TSession> {
+    const workflow = this.workflowRepository.get(decodeURIComponent(args.workflowId));
+    const displayLabel = workflow
+      ? this.workflowCredentialNodeResolver.describeCredentialNodeDisplay(workflow, args.nodeId)
+      : undefined;
+    const requirement = workflow
+      ? this.workflowCredentialNodeResolver.findRequirement(workflow, args.nodeId, args.slotKey)?.requirement
+      : undefined;
+    const bindingKey: CredentialBindingKey = {
+      workflowId: args.workflowId,
+      nodeId: args.nodeId,
+      slotKey: args.slotKey,
+    };
+    const binding = await this.credentialStore.getBinding(bindingKey);
+    if (!binding) {
+      const unbound = new CredentialUnboundError(bindingKey, requirement?.acceptedTypes ?? []);
+      if (displayLabel) {
+        throw new Error(`${displayLabel}: ${unbound.message}`, { cause: unbound });
+      }
+      throw unbound;
+    }
+    const bindingCacheKey = this.toBindingKeyString(bindingKey);
+    this.cachedInstanceIdsByBindingKey.set(bindingCacheKey, binding.instanceId);
+    const cachedSession = this.cachedSessionsByInstanceId.get(binding.instanceId);
+    if (cachedSession) {
+      return (await cachedSession) as TSession;
+    }
+    const nextSessionPromise = this.createSession(binding.instanceId, displayLabel).catch((error) => {
+      this.cachedSessionsByInstanceId.delete(binding.instanceId);
+      throw error;
+    });
+    this.cachedSessionsByInstanceId.set(binding.instanceId, nextSessionPromise);
+    return (await nextSessionPromise) as TSession;
+  }
+
+  evictInstance(instanceId: CredentialInstanceId): void {
+    this.cachedSessionsByInstanceId.delete(instanceId);
+  }
+
+  evictBinding(bindingKey: CredentialBindingKey): void {
+    const cacheKey = this.toBindingKeyString(bindingKey);
+    const instanceId = this.cachedInstanceIdsByBindingKey.get(cacheKey);
+    if (instanceId) {
+      this.cachedSessionsByInstanceId.delete(instanceId);
+    }
+    this.cachedInstanceIdsByBindingKey.delete(cacheKey);
+  }
+
+  private async createSession(instanceId: CredentialInstanceId, displayLabel?: string): Promise<unknown> {
+    const instance = await this.credentialStore.getInstance(instanceId);
+    if (!instance) {
+      throw new ApplicationRequestError(404, `Unknown credential instance: ${instanceId}`);
+    }
+    const credentialType = this.credentialTypeRegistry.getCredentialType(instance.typeId);
+    if (!credentialType) {
+      const prefix = displayLabel ? `${displayLabel}: ` : "";
+      throw new ApplicationRequestError(
+        400,
+        `${prefix}Credential type "${instance.typeId}" is not registered in this runtime (binding points at an unknown type).`,
+      );
+    }
+    const material = await this.credentialRuntimeMaterialService.compose(instance);
+    const { resolvedPublicConfig, resolvedMaterial } = this.credentialFieldEnvOverlayService.apply({
+      definition: credentialType.definition,
+      publicConfig: instance.publicConfig,
+      material,
+    });
+    return await credentialType.createSession({
+      instance,
+      material: resolvedMaterial,
+      publicConfig: resolvedPublicConfig,
+    });
+  }
+
+  private toBindingKeyString(bindingKey: CredentialBindingKey): string {
+    return `${bindingKey.workflowId}:${bindingKey.nodeId}:${bindingKey.slotKey}`;
+  }
+}

package/src/domain/credentials/CredentialTestService.ts

@@ -0,0 +1,73 @@
+import { randomUUID } from "node:crypto";
+
+import type { CredentialHealth, CredentialInstanceId, CredentialTypeId } from "@codemation/core";
+
+import { CoreTokens, inject, injectable } from "@codemation/core";
+
+import { ApplicationRequestError } from "../../application/ApplicationRequestError";
+
+import { ApplicationTokens } from "../../applicationTokens";
+
+import { CredentialFieldEnvOverlayService } from "./CredentialFieldEnvOverlayService";
+import { CredentialInstanceService } from "./CredentialInstanceService";
+import { CredentialRuntimeMaterialService } from "./CredentialRuntimeMaterialService";
+import type { CredentialStore, AnyCredentialType, MutableCredentialSessionService } from "./CredentialServices";
+import { CredentialTypeRegistryImpl } from "./CredentialServices";
+
+@injectable()
+export class CredentialTestService {
+  constructor(
+    @inject(CredentialInstanceService)
+    private readonly credentialInstanceService: CredentialInstanceService,
+    @inject(CredentialRuntimeMaterialService)
+    private readonly credentialRuntimeMaterialService: CredentialRuntimeMaterialService,
+    @inject(CredentialFieldEnvOverlayService)
+    private readonly credentialFieldEnvOverlayService: CredentialFieldEnvOverlayService,
+    @inject(CredentialTypeRegistryImpl)
+    private readonly credentialTypeRegistry: CredentialTypeRegistryImpl,
+    @inject(ApplicationTokens.CredentialStore)
+    private readonly credentialStore: CredentialStore,
+    @inject(CoreTokens.CredentialSessionService)
+    private readonly credentialSessionService: MutableCredentialSessionService,
+  ) {}
+
+  async test(instanceId: CredentialInstanceId): Promise<CredentialHealth> {
+    const instance = await this.credentialInstanceService.requireInstance(instanceId);
+    const credentialType = this.requireCredentialType(instance.typeId);
+    const material = await this.credentialRuntimeMaterialService.compose(instance);
+    const { resolvedPublicConfig, resolvedMaterial } = this.credentialFieldEnvOverlayService.apply({
+      definition: credentialType.definition,
+      publicConfig: instance.publicConfig,
+      material,
+    });
+    const health = await credentialType.test({
+      instance,
+      material: resolvedMaterial,
+      publicConfig: resolvedPublicConfig,
+    });
+    const testedAt = health.testedAt ?? new Date().toISOString();
+    await this.credentialStore.saveTestResult({
+      testId: randomUUID(),
+      instanceId,
+      health: {
+        ...health,
+        testedAt,
+      },
+      testedAt,
+      expiresAt: health.expiresAt,
+    });
+    this.credentialSessionService.evictInstance(instanceId);
+    return {
+      ...health,
+      testedAt,
+    };
+  }
+
+  private requireCredentialType(typeId: CredentialTypeId): AnyCredentialType {
+    const credentialType = this.credentialTypeRegistry.getCredentialType(typeId);
+    if (!credentialType) {
+      throw new ApplicationRequestError(400, `Unknown credential type: ${typeId}`);
+    }
+    return credentialType;
+  }
+}

package/src/domain/credentials/CredentialTypeRegistryImpl.ts

@@ -0,0 +1,29 @@
+import type { CredentialTypeDefinition, CredentialTypeId, CredentialTypeRegistry } from "@codemation/core";
+
+import { injectable } from "@codemation/core";
+
+import type { AnyCredentialType, CredentialType } from "./CredentialServices";
+
+@injectable()
+export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
+  private readonly credentialTypesById = new Map<CredentialTypeId, AnyCredentialType>();
+
+  register(type: CredentialType<any, any, unknown>): void {
+    if (this.credentialTypesById.has(type.definition.typeId)) {
+      throw new Error(`Credential type already registered: ${type.definition.typeId}`);
+    }
+    this.credentialTypesById.set(type.definition.typeId, type);
+  }
+
+  listTypes(): ReadonlyArray<CredentialTypeDefinition> {
+    return [...this.credentialTypesById.values()].map((entry) => entry.definition);
+  }
+
+  getType(typeId: CredentialTypeId): CredentialTypeDefinition | undefined {
+    return this.credentialTypesById.get(typeId)?.definition;
+  }
+
+  getCredentialType(typeId: CredentialTypeId): AnyCredentialType | undefined {
+    return this.credentialTypesById.get(typeId);
+  }
+}