@codemation/host 0.6.0 → 0.8.0

package/src/domain/credentials/CredentialTypeRegistryImpl.ts

@@ -1,29 +1,136 @@
 import type { CredentialTypeDefinition, CredentialTypeId, CredentialTypeRegistry } from "@codemation/core";
 
-import { injectable } from "@codemation/core";
+import { inject, injectable } from "@codemation/core";
 
-import type { AnyCredentialType, CredentialType } from "./CredentialServices";
+import { ApplicationTokens } from "../../applicationTokens";
+import type { LoggerFactory } from "../../application/logging/Logger";
+import type { AnyCredentialType } from "./CredentialServices";
+
+export type CredentialTypeSource = "plugin" | "config" | "controlPlane";
+
+const SOURCE_PRIORITY: Record<CredentialTypeSource, number> = {
+  plugin: 0,
+  config: 1,
+  controlPlane: 2,
+};
+
+type RegistryEntry = Readonly<{
+  type: AnyCredentialType;
+  source: CredentialTypeSource;
+}>;
 
 @injectable()
 export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
-  private readonly credentialTypesById = new Map<CredentialTypeId, AnyCredentialType>();
+  private readonly entries = new Map<CredentialTypeId, RegistryEntry>();
+  private readonly bySource = new Map<CredentialTypeSource, Set<CredentialTypeId>>();
 
-  register(type: CredentialType<any, any, unknown>): void {
-    if (this.credentialTypesById.has(type.definition.typeId)) {
-      throw new Error(`Credential type already registered: ${type.definition.typeId}`);
+  constructor(@inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory) {}
+
+  merge(source: CredentialTypeSource, types: ReadonlyArray<AnyCredentialType>): void {
+    const logger = this.loggers.create("CredentialTypeRegistryImpl");
+    for (const type of types) {
+      this.insert(source, type, logger);
+    }
+  }
+
+  mergeDefinitions(source: CredentialTypeSource, definitions: ReadonlyArray<CredentialTypeDefinition>): void {
+    const logger = this.loggers.create("CredentialTypeRegistryImpl");
+    for (const definition of definitions) {
+      const existing = this.entries.get(definition.typeId);
+      const sourcePriority = SOURCE_PRIORITY[source];
+      if (existing) {
+        if (sourcePriority < SOURCE_PRIORITY[existing.source]) {
+          logger.warn(
+            `CredentialTypeRegistryImpl: id collision — lower-priority source "${source}" ignored for typeId "${definition.typeId}" (current source: "${existing.source}")`,
+          );
+          continue;
+        }
+        if (sourcePriority > SOURCE_PRIORITY[existing.source]) {
+          logger.warn(
+            `CredentialTypeRegistryImpl: typeId "${definition.typeId}" shadowed — "${existing.source}" overridden by higher-priority source "${source}"`,
+          );
+          this.bySource.get(existing.source)?.delete(definition.typeId);
+        }
+        const nextType: AnyCredentialType =
+          sourcePriority === SOURCE_PRIORITY[existing.source]
+            ? { ...existing.type, definition }
+            : { definition, createSession: this.createUnsupportedSessionFactory(definition.typeId, source), test: this.createUnsupportedHealthTester(definition.typeId, source) };
+        this.recordEntry(definition.typeId, { type: nextType, source });
+        continue;
+      }
+      const stubType: AnyCredentialType = {
+        definition,
+        createSession: this.createUnsupportedSessionFactory(definition.typeId, source),
+        test: this.createUnsupportedHealthTester(definition.typeId, source),
+      };
+      this.recordEntry(definition.typeId, { type: stubType, source });
+    }
+  }
+
+  clear(source: CredentialTypeSource): void {
+    const ids = this.bySource.get(source);
+    if (!ids) {
+      return;
+    }
+    for (const id of ids) {
+      this.entries.delete(id);
     }
-    this.credentialTypesById.set(type.definition.typeId, type);
+    this.bySource.delete(source);
   }
 
   listTypes(): ReadonlyArray<CredentialTypeDefinition> {
-    return [...this.credentialTypesById.values()].map((entry) => entry.definition);
+    return [...this.entries.values()].map((entry) => entry.type.definition);
   }
 
   getType(typeId: CredentialTypeId): CredentialTypeDefinition | undefined {
-    return this.credentialTypesById.get(typeId)?.definition;
+    return this.entries.get(typeId)?.type.definition;
   }
 
   getCredentialType(typeId: CredentialTypeId): AnyCredentialType | undefined {
-    return this.credentialTypesById.get(typeId);
+    return this.entries.get(typeId)?.type;
+  }
+
+  private insert(source: CredentialTypeSource, type: AnyCredentialType, logger: ReturnType<LoggerFactory["create"]>): void {
+    const typeId = type.definition.typeId;
+    const existing = this.entries.get(typeId);
+    const sourcePriority = SOURCE_PRIORITY[source];
+    if (existing) {
+      if (sourcePriority < SOURCE_PRIORITY[existing.source]) {
+        logger.warn(
+          `CredentialTypeRegistryImpl: id collision — lower-priority source "${source}" ignored for typeId "${typeId}" (current source: "${existing.source}")`,
+        );
+        return;
+      }
+      if (sourcePriority > SOURCE_PRIORITY[existing.source]) {
+        logger.warn(
+          `CredentialTypeRegistryImpl: typeId "${typeId}" shadowed — "${existing.source}" overridden by higher-priority source "${source}"`,
+        );
+        this.bySource.get(existing.source)?.delete(typeId);
+      }
+    }
+    this.recordEntry(typeId, { type, source });
+  }
+
+  private recordEntry(typeId: CredentialTypeId, entry: RegistryEntry): void {
+    this.entries.set(typeId, entry);
+    if (!this.bySource.has(entry.source)) {
+      this.bySource.set(entry.source, new Set());
+    }
+    this.bySource.get(entry.source)!.add(typeId);
+  }
+
+  private createUnsupportedSessionFactory(typeId: CredentialTypeId, source: CredentialTypeSource): AnyCredentialType["createSession"] {
+    return async () => {
+      throw new Error(
+        `Credential type "${typeId}" (source "${source}") was registered with definition only — no createSession implementation is available in this runtime.`,
+      );
+    };
+  }
+
+  private createUnsupportedHealthTester(typeId: CredentialTypeId, source: CredentialTypeSource): AnyCredentialType["test"] {
+    return async () => ({
+      status: "unknown" as const,
+      message: `Credential type "${typeId}" (source "${source}") has no local test implementation.`,
+    });
   }
 }

package/src/domain/credentials/OAuth2RedirectUriResolver.ts

@@ -0,0 +1,79 @@
+import { inject, injectable } from "@codemation/core";
+import { ApplicationRequestError } from "../../application/ApplicationRequestError";
+import { ApplicationTokens } from "../../applicationTokens";
+import type { AppConfig } from "../../presentation/config/AppConfig";
+
+/**
+ * Resolves the canonical OAuth2 redirect URI from the public base URL or request origin.
+ * The redirect URI always points to `/api/oauth2/callback`, which is the URL operators
+ * register with their OAuth provider.
+ */
+@injectable()
+export class OAuth2RedirectUriResolver {
+  constructor(
+    @inject(ApplicationTokens.AppConfig)
+    private readonly appConfig: AppConfig,
+  ) {}
+
+  resolve(requestOrigin: string): string {
+    const rawBase = this.appConfig.env.CODEMATION_PUBLIC_BASE_URL?.trim() || requestOrigin.trim();
+    if (!rawBase) {
+      throw new Error("Unable to resolve the public base URL for OAuth2 redirect URI generation.");
+    }
+    const baseUrl = this.ensureAbsoluteUrl(rawBase);
+    try {
+      const callback = new URL("/api/oauth2/callback", this.normalizeBaseUrl(baseUrl));
+      // Several OAuth2 providers (notably Azure AD / Microsoft) reject raw loopback IPs in
+      // redirect URIs and only allow the `localhost` hostname. 127.0.0.1 / [::1] are equivalent
+      // to localhost by definition, so rewriting is lossless.
+      const loopbackHostnames = new Set(["127.0.0.1", "[::1]"]);
+      if (loopbackHostnames.has(callback.hostname)) {
+        callback.hostname = "localhost";
+      }
+      return callback.toString();
+    } catch {
+      throw new ApplicationRequestError(
+        500,
+        `Invalid public base URL for OAuth2 redirect URI generation: "${rawBase}". Use a full URL (e.g. http://localhost:3000) for CODEMATION_PUBLIC_BASE_URL or ensure the request has a valid Host / forwarded headers.`,
+      );
+    }
+  }
+
+  /**
+   * Ensures the base URL has an http/https scheme. Comma-separated values (proxy chains) use
+   * the first segment only.
+   */
+  private ensureAbsoluteUrl(raw: string): string {
+    const segments = raw
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+    let candidate = segments[0] ?? raw.trim();
+    if (!candidate) {
+      throw new Error("Unable to resolve the public base URL for OAuth2 redirect URI generation.");
+    }
+    if (!/^https?:\/\//i.test(candidate)) {
+      candidate = `http://${candidate}`;
+    }
+    let parsed: URL;
+    try {
+      parsed = new URL(candidate);
+    } catch {
+      throw new ApplicationRequestError(
+        500,
+        `Invalid public base URL for OAuth2 redirect URI generation: "${raw}". Use a single full URL (e.g. http://localhost:3000) for CODEMATION_PUBLIC_BASE_URL.`,
+      );
+    }
+    if (parsed.hostname === "http" || parsed.hostname === "https") {
+      throw new ApplicationRequestError(
+        500,
+        `Invalid OAuth2 public base URL (hostname "${parsed.hostname}"). Set CODEMATION_PUBLIC_BASE_URL to one full URL with a real host, e.g. http://localhost:3000 — not "http,http" or other typos.`,
+      );
+    }
+    return candidate;
+  }
+
+  private normalizeBaseUrl(baseUrl: string): string {
+    return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  }
+}

package/src/domain/credentials/WorkflowCredentialNodeResolver.ts

@@ -4,9 +4,10 @@ import {
   AgentConnectionNodeCollector,
   type AgentConnectionNodeDescriptor,
   ConnectionNodeIdFactory,
+  inject,
+  injectable,
 } from "@codemation/core";
-
-import { injectable } from "@codemation/core";
+import { McpServerCatalog } from "../../mcp/McpServerCatalog";
 
 export type WorkflowCredentialSlotRef = Readonly<{
   workflowId: string;
@@ -20,6 +21,10 @@ export type WorkflowCredentialSlotRef = Readonly<{
  */
 @injectable()
 export class WorkflowCredentialNodeResolver {
+  constructor(
+    @inject(McpServerCatalog)
+    private readonly mcpCatalog?: McpServerCatalog,
+  ) {}
   /**
    * Human-readable label for credential errors (workflow node name or agent › attachment).
    */
@@ -102,7 +107,9 @@ export class WorkflowCredentialNodeResolver {
     agentConfig: Parameters<typeof AgentConnectionNodeCollector.collect>[1],
     slotsByKey: Map<string, WorkflowCredentialSlotRef>,
   ): void {
-    for (const entry of AgentConnectionNodeCollector.collect(rootAgentNodeId, agentConfig)) {
+    const mcpResolver = this.mcpCatalog ? (id: string) => this.mcpCatalog!.get(id) : undefined;
+    const descriptors = AgentConnectionNodeCollector.collect(rootAgentNodeId, agentConfig, mcpResolver);
+    for (const entry of descriptors) {
       this.addSlotsForRequirements(
         workflowId,
         entry.nodeId,
@@ -147,15 +154,17 @@ export class WorkflowCredentialNodeResolver {
     | undefined {
     if (
       !ConnectionNodeIdFactory.isLanguageModelConnectionNodeId(nodeId) &&
-      !ConnectionNodeIdFactory.isToolConnectionNodeId(nodeId)
+      !ConnectionNodeIdFactory.isToolConnectionNodeId(nodeId) &&
+      !ConnectionNodeIdFactory.isMcpConnectionNodeId(nodeId)
     ) {
       return undefined;
     }
+    const mcpResolver = this.mcpCatalog ? (id: string) => this.mcpCatalog!.get(id) : undefined;
     for (const node of workflow.nodes) {
       if (!AgentConfigInspector.isAgentNodeConfig(node.config)) {
         continue;
       }
-      const entries = AgentConnectionNodeCollector.collect(node.id, node.config);
+      const entries = AgentConnectionNodeCollector.collect(node.id, node.config, mcpResolver);
       const entriesById = new Map(entries.map((entry) => [entry.nodeId, entry]));
       const entry = entriesById.get(nodeId);
       if (!entry) {

package/src/domain/telemetry/TelemetryContracts.ts

@@ -86,6 +86,8 @@ export interface TelemetryArtifactRecord {
   readonly previewJson?: unknown;
   readonly payloadText?: string;
   readonly payloadJson?: unknown;
+  /** Set when the payload was offloaded to BinaryStorage (byteLength > 64 KB). */
+  readonly payloadStorageKey?: string;
   readonly bytes?: number;
   readonly truncated?: boolean;
   readonly createdAt: string;
@@ -195,7 +197,11 @@ export interface TelemetrySpanStore {
 export interface TelemetryArtifactStore {
   save(record: TelemetryArtifactWrite): Promise<TelemetryArtifactRecord>;
   listByTraceId(traceId: string): Promise<ReadonlyArray<TelemetryArtifactRecord>>;
-  pruneExpired(args: TelemetryPruneArgs): Promise<number>;
+  /**
+   * Deletes expired artifacts. Returns the count of deleted rows and any
+   * `payloadStorageKey` references that callers must clean up from BinaryStorage.
+   */
+  pruneExpired(args: TelemetryPruneArgs): Promise<{ count: number; storageKeys: ReadonlyArray<string> }>;
 }
 
 export interface TelemetryMetricPointStore {

package/src/domain/workflows/WorkflowActivationPreflight.ts

@@ -1,6 +1,9 @@
 import { ApplicationRequestError } from "../../application/ApplicationRequestError";
-import { CoreTokens, inject, injectable, type WorkflowRepository } from "@codemation/core";
+import { ApplicationTokens } from "../../applicationTokens";
+import { CoreTokens, inject, injectable, type CredentialTypeRegistry, type WorkflowRepository } from "@codemation/core";
 import { CredentialBindingService } from "../credentials/CredentialServices";
+import { CredentialOAuth2ScopeResolver } from "../credentials/CredentialOAuth2ScopeResolver";
+import type { CredentialStore } from "../credentials/CredentialServices";
 import { WorkflowActivationPreflightRules } from "./WorkflowActivationPreflightRules";
 
 @injectable()
@@ -12,6 +15,12 @@ export class WorkflowActivationPreflight {
     private readonly credentialBindingService: CredentialBindingService,
     @inject(WorkflowActivationPreflightRules)
     private readonly rules: WorkflowActivationPreflightRules,
+    @inject(CoreTokens.CredentialTypeRegistry)
+    private readonly credentialTypeRegistry: CredentialTypeRegistry,
+    @inject(ApplicationTokens.CredentialStore)
+    private readonly credentialStore: CredentialStore,
+    @inject(CredentialOAuth2ScopeResolver)
+    private readonly credentialOAuth2ScopeResolver: CredentialOAuth2ScopeResolver,
   ) {}
 
   async assertCanActivate(workflowId: string): Promise<void> {
@@ -21,9 +30,23 @@ export class WorkflowActivationPreflight {
       throw new ApplicationRequestError(404, `Unknown workflowId: ${decodedId}`);
     }
     const health = await this.credentialBindingService.listWorkflowHealth(decodedId);
+    const scopeErrors = await this.rules.collectScopeMismatchErrors(health, {
+      getRequiredScopes: (typeId, _requirement) => {
+        const type = this.credentialTypeRegistry.getType(typeId);
+        if (type?.auth?.kind === "oauth2") {
+          return this.credentialOAuth2ScopeResolver.resolveRequestedScopes(type.auth, {});
+        }
+        return [];
+      },
+      getGrantedScopes: async (instanceId) => {
+        const material = await this.credentialStore.getOAuth2Material(instanceId);
+        return material?.scopes ?? [];
+      },
+    });
     const errors = [
       ...this.rules.collectNonManualTriggerErrors(workflow),
       ...this.rules.collectRequiredCredentialErrors(health),
+      ...scopeErrors,
     ];
     if (errors.length > 0) {
       throw new ApplicationRequestError(400, "Workflow cannot be activated.", errors);

package/src/domain/workflows/WorkflowActivationPreflightRules.ts

@@ -1,5 +1,5 @@
 import type { WorkflowCredentialHealthDto } from "../../application/contracts/CredentialContractsRegistry";
-import { getPersistedRuntimeTypeMetadata, injectable, type WorkflowDefinition } from "@codemation/core";
+import { getPersistedRuntimeTypeMetadata, injectable, type CredentialRequirement, type WorkflowDefinition } from "@codemation/core";
 import { MissingRuntimeTriggerToken } from "@codemation/core/bootstrap";
 import { ManualTriggerNode } from "@codemation/core-nodes";
 
@@ -74,4 +74,43 @@ export class WorkflowActivationPreflightRules {
     }
     return lines;
   }
+
+  async collectScopeMismatchErrors(
+    health: WorkflowCredentialHealthDto,
+    opts: {
+      getRequiredScopes: (typeId: string, slotRequirement: CredentialRequirement) => ReadonlyArray<string>;
+      getGrantedScopes: (instanceId: string) => Promise<ReadonlyArray<string>>;
+    },
+  ): Promise<ReadonlyArray<string>> {
+    const checked = new Set<string>();
+    const lines: string[] = [];
+
+    for (const slot of health.slots) {
+      const { instance } = slot;
+      if (!instance) {
+        continue;
+      }
+      const { instanceId, typeId, displayName } = instance;
+      if (checked.has(instanceId)) {
+        continue;
+      }
+      checked.add(instanceId);
+
+      const required = opts.getRequiredScopes(typeId, slot.requirement);
+      if (required.length === 0) {
+        continue;
+      }
+
+      const granted = await opts.getGrantedScopes(instanceId);
+      const grantedSet = new Set(granted);
+      const missing = required.filter((s) => !grantedSet.has(s));
+      if (missing.length > 0) {
+        lines.push(
+          `Credential "${displayName}" missing scopes: ${missing.join(", ")}. Reconnect to grant.`,
+        );
+      }
+    }
+
+    return lines;
+  }
 }

package/src/index.ts

@@ -6,11 +6,16 @@ export { UpsertLocalBootstrapUserCommand } from "./application/commands/UpsertLo
 export type { UpsertLocalBootstrapUserResultDto } from "./application/contracts/userDirectoryContracts.types";
 export { AppContainerFactory } from "./bootstrap/AppContainerFactory";
 export { AppContainerLifecycle } from "./bootstrap/AppContainerLifecycle";
+export { BootTimer } from "./bootstrap/perf/BootTimer";
+export type { BootTracePhase } from "./bootstrap/perf/BootTimer";
 export { DatabaseMigrations } from "./bootstrap/runtime/DatabaseMigrations";
 export { CollectionSchemaSyncerHolder } from "./infrastructure/collections/CollectionSchemaSyncerHolder";
 export { FrontendRuntime } from "./bootstrap/runtime/FrontendRuntime";
 export { WorkerRuntime } from "./bootstrap/runtime/WorkerRuntime";
 export { AppConfigFactory } from "./bootstrap/runtime/AppConfigFactory";
+export { HeadlessApiRuntime } from "./bootstrap/runtime/HeadlessApiRuntime";
+export { WorkflowWebsocketServerFactory } from "./presentation/websocket/WorkflowWebsocketServerFactory";
+export { HeadlessHttpServerFactory } from "./presentation/http/HeadlessHttpServerFactory";
 export { ApplicationTokens } from "./applicationTokens";
 export { workflow } from "@codemation/core-nodes";
 export { CodemationBootstrapRequest } from "./bootstrap/CodemationBootstrapRequest";
@@ -56,6 +61,10 @@ export { InsertCollectionRowCommand } from "./application/collections/InsertColl
 export { UpdateCollectionRowCommand } from "./application/collections/UpdateCollectionRowCommand";
 export { DeleteCollectionRowCommand } from "./application/collections/DeleteCollectionRowCommand";
 export { SyncCollectionsCommand } from "./application/collections/SyncCollectionsCommand";
+export { StartWorkflowRunCommand } from "./application/commands/StartWorkflowRunCommand";
+export type { RunCommandResult } from "./application/contracts/RunContracts";
+export { ApplicationRequestError } from "./application/ApplicationRequestError";
+export { GetRunStateQuery } from "./application/queries/GetRunStateQuery";
 
 export type {
   CodemationFrontendAuthProviderSnapshot,

package/src/infrastructure/binary/LocalFilesystemBinaryStorageRegistry.ts

@@ -1,6 +1,6 @@
 import { createReadStream, createWriteStream } from "node:fs";
 
-import { mkdir, rm, stat } from "node:fs/promises";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
 
 import path from "node:path";
 
@@ -72,6 +72,34 @@ export class LocalFilesystemBinaryStorage implements BinaryStorage {
     await rm(this.resolveAbsolutePath(storageKey), { force: true });
   }
 
+  async deleteMany(storageKeys: ReadonlyArray<string>): Promise<void> {
+    await Promise.all(storageKeys.map((key) => this.delete(key)));
+  }
+
+  async listByPrefix(prefix: string): Promise<ReadonlyArray<string>> {
+    const results: string[] = [];
+    await this.collectKeysWithPrefix(prefix, this.baseDirectory, results);
+    return results;
+  }
+
+  private async collectKeysWithPrefix(prefix: string, dir: string, results: string[]): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const entryPath = path.join(dir, entry.name);
+      const relKey = path.relative(path.resolve(this.baseDirectory), entryPath).replace(/\\/g, "/");
+      if (entry.isDirectory()) {
+        await this.collectKeysWithPrefix(prefix, entryPath, results);
+      } else if (relKey.startsWith(prefix)) {
+        results.push(relKey);
+      }
+    }
+  }
+
   private resolveAbsolutePath(storageKey: string): string {
     const absoluteBaseDirectory = path.resolve(this.baseDirectory);
     const targetPath = path.resolve(absoluteBaseDirectory, storageKey);

package/src/infrastructure/binary/S3BinaryStorage.ts

@@ -0,0 +1,169 @@
+import { PassThrough, Readable } from "node:stream";
+
+import {
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  HeadBucketCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  S3Client,
+} from "@aws-sdk/client-s3";
+
+import { Upload } from "@aws-sdk/lib-storage";
+
+import type {
+  BinaryBody,
+  BinaryStorage,
+  BinaryStorageReadResult,
+  BinaryStorageStatResult,
+  BinaryStorageWriteResult,
+} from "@codemation/core";
+
+import { BinaryBodyNodeReadableFactory } from "./BinaryBodyNodeReadableFactory";
+import type { S3BinaryStorageConfig } from "./S3BinaryStorageConfig";
+
+const DELETE_BATCH_SIZE = 1000;
+
+export class S3BinaryStorage implements BinaryStorage {
+  readonly driverName = "s3";
+
+  private readonly client: S3Client;
+  private readonly bucket: string;
+
+  /**
+   * @param config - S3 connection details.
+   * @param forcePathStyle - Use path-style addressing (true for MinIO / testcontainers; false for Scaleway). Default false.
+   */
+  constructor(config: S3BinaryStorageConfig, forcePathStyle = false) {
+    this.bucket = config.bucket;
+    this.client = new S3Client({
+      endpoint: config.endpoint,
+      region: config.region,
+      forcePathStyle,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey,
+      },
+    });
+  }
+
+  async write(args: { storageKey: string; body: BinaryBody }): Promise<BinaryStorageWriteResult> {
+    const readable = new BinaryBodyNodeReadableFactory(args.body).create();
+    let size = 0;
+    const passThrough = new PassThrough();
+    readable.on("data", (chunk: Buffer) => {
+      size += chunk.byteLength;
+    });
+    readable.pipe(passThrough);
+
+    const upload = new Upload({
+      client: this.client,
+      params: {
+        Bucket: this.bucket,
+        Key: args.storageKey,
+        Body: passThrough,
+      },
+    });
+
+    await upload.done();
+
+    return {
+      storageKey: args.storageKey,
+      size,
+    };
+  }
+
+  async openReadStream(storageKey: string): Promise<BinaryStorageReadResult | undefined> {
+    const { GetObjectCommand } = await import("@aws-sdk/client-s3");
+    let response;
+    try {
+      response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: storageKey }));
+    } catch (err) {
+      if (this.isNotFoundError(err)) {
+        return undefined;
+      }
+      throw err;
+    }
+
+    if (!response.Body) {
+      return undefined;
+    }
+
+    const nodeReadable = Readable.from(response.Body as AsyncIterable<Uint8Array>);
+    return {
+      body: Readable.toWeb(nodeReadable) as BinaryStorageReadResult["body"],
+      size: response.ContentLength,
+    };
+  }
+
+  async stat(storageKey: string): Promise<BinaryStorageStatResult> {
+    try {
+      const response = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: storageKey }));
+      return { exists: true, size: response.ContentLength };
+    } catch (err) {
+      if (this.isNotFoundError(err)) {
+        return { exists: false };
+      }
+      throw err;
+    }
+  }
+
+  async delete(storageKey: string): Promise<void> {
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: storageKey }));
+  }
+
+  async deleteMany(storageKeys: ReadonlyArray<string>): Promise<void> {
+    for (let i = 0; i < storageKeys.length; i += DELETE_BATCH_SIZE) {
+      const batch = storageKeys.slice(i, i + DELETE_BATCH_SIZE);
+      await this.client.send(
+        new DeleteObjectsCommand({
+          Bucket: this.bucket,
+          Delete: {
+            Objects: batch.map((key) => ({ Key: key })),
+            Quiet: true,
+          },
+        }),
+      );
+    }
+  }
+
+  async listByPrefix(prefix: string): Promise<ReadonlyArray<string>> {
+    const keys: string[] = [];
+    let continuationToken: string | undefined;
+
+    do {
+      const response = await this.client.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: prefix,
+          ContinuationToken: continuationToken,
+        }),
+      );
+
+      for (const obj of response.Contents ?? []) {
+        if (obj.Key) {
+          keys.push(obj.Key);
+        }
+      }
+
+      continuationToken = response.NextContinuationToken;
+    } while (continuationToken);
+
+    return keys;
+  }
+
+  /** Checks that the configured bucket is reachable. Throws if not. */
+  async checkConnectivity(): Promise<void> {
+    await this.client.send(new HeadBucketCommand({ Bucket: this.bucket }));
+  }
+
+  private isNotFoundError(err: unknown): boolean {
+    if (typeof err !== "object" || err === null) {
+      return false;
+    }
+    const anyErr = err as Record<string, unknown>;
+    const statusCode =
+      anyErr["$metadata"] != null ? (anyErr["$metadata"] as Record<string, unknown>)["httpStatusCode"] : undefined;
+    return statusCode === 404 || anyErr["name"] === "NotFound" || anyErr["name"] === "NoSuchKey";
+  }
+}

package/src/infrastructure/binary/S3BinaryStorageConfig.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export interface S3BinaryStorageConfig {
+  readonly endpoint: string;
+  readonly region: string;
+  readonly bucket: string;
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+}
+
+export const S3BinaryStorageConfigSchema = z.object({
+  endpoint: z.string().min(1),
+  region: z.string().min(1),
+  bucket: z.string().min(1),
+  accessKeyId: z.string().min(1),
+  secretAccessKey: z.string().min(1),
+});