@smthrs/control 0.0.0-stage → 1.0.0-rc.4

package/src/SqlCredentialStore.ts

@@ -0,0 +1,148 @@
+/**
+ * Durable credential persistence over `@smthrs/database`.
+ *
+ * This is the host adapter behind {@link CredentialStore} on any runtime with
+ * a SQL database — the Node composition uses `@smthrs/database/node`, and
+ * tests use its in-memory SQLite driver. The module itself imports no `node:*`
+ * API: it speaks the driver-neutral SQL contract, so it stays bundleable and a
+ * browser host that ships a SQL driver can use it unchanged.
+ *
+ * Only ciphertext is stored. The row carries no key material, and the
+ * compare-and-set on `version` is what makes two concurrent rotations
+ * serializable: the loser is refused with `CredentialConflict` instead of
+ * clobbering the winner.
+ *
+ * @since 0.1.0
+ */
+
+import { DurableWriter } from "@smthrs/database/DurableWriter"
+import { Effect, Layer, Option } from "effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+import { CredentialConflict, Unavailable } from "./ControlError.ts"
+import * as CredentialStore from "./CredentialStore.ts"
+import { initial } from "./migrations/0001_control_tables.ts"
+
+interface Row {
+  readonly id: string
+  readonly name: string
+  readonly ciphertext: string
+  readonly nonce: string
+  readonly version: number
+  readonly updated_at_ms: number
+}
+
+const toRecord = (row: Row): CredentialStore.SealedRecord => ({
+  id: row.id,
+  name: row.name,
+  ciphertext: row.ciphertext,
+  nonce: row.nonce,
+  version: Number(row.version),
+  updatedAtMs: Number(row.updated_at_ms)
+})
+
+const unavailable = (operation: string) => (): Unavailable =>
+  new Unavailable({
+    feature: `credential storage (${operation})`,
+    ticket: "control-credential-storage"
+  })
+
+/**
+ * Creates the credential table if it does not exist.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const migrate: Effect.Effect<void, Unavailable, SqlClient.SqlClient> = initial.pipe(
+  Effect.mapError(unavailable("migrate"))
+)
+
+/**
+ * Constructs a durable credential store over the ambient database.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make: Effect.Effect<
+  CredentialStore.Service,
+  Unavailable,
+  DurableWriter | SqlClient.SqlClient
+> = Effect.gen(function*() {
+  const sql = yield* Effect.service(SqlClient.SqlClient)
+  const writer = yield* DurableWriter
+  yield* migrate
+
+  const list = (): Effect.Effect<ReadonlyArray<CredentialStore.SealedRecord>, Unavailable> =>
+    sql<Row>`SELECT * FROM control_credentials ORDER BY name`.pipe(
+      Effect.map((rows) => rows.map(toRecord)),
+      Effect.mapError(unavailable("list"))
+    )
+
+  const read = (id: string): Effect.Effect<Option.Option<CredentialStore.SealedRecord>, Unavailable> =>
+    sql<Row>`SELECT * FROM control_credentials WHERE id = ${id}`.pipe(
+      Effect.map((rows) => Option.map(Option.fromNullishOr(rows[0]), toRecord)),
+      Effect.mapError(unavailable("read"))
+    )
+
+  // One write transaction, so the version this writer read and the row it
+  // guards cannot interleave with a concurrent rotation.
+  const write = (
+    record: CredentialStore.SealedRecord
+  ): Effect.Effect<void, Unavailable | CredentialConflict> =>
+    writer.write(Effect.gen(function*() {
+      const rows = yield* sql<{ readonly version: number }>`
+        SELECT version FROM control_credentials WHERE id = ${record.id}
+      `
+      const stored = rows[0]
+      const actual = stored === undefined ? 0 : Number(stored.version)
+      if (actual !== record.version - 1) {
+        return yield* Effect.fail(
+          new CredentialConflict({
+            id: record.id,
+            expectedVersion: record.version - 1,
+            actualVersion: actual
+          })
+        )
+      }
+      yield* sql`
+        INSERT INTO control_credentials (id, name, ciphertext, nonce, version, updated_at_ms)
+        VALUES (
+          ${record.id},
+          ${record.name},
+          ${record.ciphertext},
+          ${record.nonce},
+          ${record.version},
+          ${record.updatedAtMs}
+        )
+        ON CONFLICT (id) DO UPDATE SET
+          name = excluded.name,
+          ciphertext = excluded.ciphertext,
+          nonce = excluded.nonce,
+          version = excluded.version,
+          updated_at_ms = excluded.updated_at_ms
+      `
+    })).pipe(
+      Effect.mapError((cause): Unavailable | CredentialConflict =>
+        cause instanceof CredentialConflict ? cause : unavailable("write")()
+      )
+    )
+
+  const remove = (id: string): Effect.Effect<void, Unavailable> =>
+    sql`DELETE FROM control_credentials WHERE id = ${id}`.pipe(
+      Effect.asVoid,
+      Effect.mapError(unavailable("remove"))
+    )
+
+  return CredentialStore.make({ list, read, write, remove })
+})
+
+/**
+ * Provides durable credential persistence over the ambient database.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer: Layer.Layer<
+  CredentialStore.CredentialStore,
+  Unavailable,
+  DurableWriter | SqlClient.SqlClient
+> = Layer.effect(CredentialStore.CredentialStore)(make)

package/src/Steering.ts

@@ -0,0 +1,96 @@
+/**
+ * The steer lifecycle as the control plane reads it back.
+ *
+ * A steer has two durable moments and two different writers. The control plane
+ * records the first — `control.steer.enqueued`, written beside the admission
+ * it caused. The second belongs to `@smthrs/notifications`: a turn boundary
+ * promotes the notification and the queue journals the promotion. This module
+ * projects that promotion into the control vocabulary, so a watcher folds one
+ * stream instead of two, and so nothing writes "delivered" twice.
+ *
+ * Deriving rather than re-recording is what keeps the two halves honest. A
+ * control plane that emitted its own delivery record would be asserting a fact
+ * it did not observe: the boundary that delivered the steer runs in the agent
+ * process, not this one.
+ *
+ * @since 0.1.0
+ */
+
+import type { ControlEvent } from "./ControlSchema.ts"
+
+/**
+ * The journal event type the notification queue records a promotion under.
+ *
+ * Named as a string rather than imported so this projection reads a journal
+ * written by any queue implementation, exactly as `Lineage` reads engine
+ * decisions.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const promotedEventType = "flows/notifications/Promoted"
+
+/**
+ * The kind `watch` reports one delivered steer under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const deliveredEventType = "control.steer.delivered"
+
+/**
+ * The kind `Control.steer` records an accepted steer under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const enqueuedEventType = "control.steer.enqueued"
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Readonly<Record<string, unknown>>
+    : undefined
+
+const strings = (value: unknown): ReadonlyArray<string> =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : []
+
+/**
+ * Derives one delivery delta per message a promotion entry named.
+ *
+ * A boundary promotes a batch, so one entry can disclose several deliveries.
+ * Each delta carries the source sequence and the boundary that took it.
+ * `ControlLive.watch` adds an expansion cursor so a consumer can resume
+ * between deliveries in the same batch.
+ *
+ * A promotion that named nothing derives nothing: an idle boundary drains an
+ * empty queue on every turn, and reporting that as a delivery would bury the
+ * real ones.
+ *
+ * @param event the projected journal entry
+ * @category projections
+ * @since 0.1.0
+ */
+export const derive = (event: ControlEvent): ReadonlyArray<ControlEvent> => {
+  const runId = event.runId
+  if (event.kind !== promotedEventType || runId === undefined) return []
+  const payload = record(event.payload)
+  if (payload === undefined) return []
+  const boundary = typeof payload["boundary"] === "string" ? payload["boundary"] : undefined
+  if (boundary === undefined) return []
+  return strings(payload["ids"]).map((messageId): ControlEvent => ({
+    sequence: event.sequence,
+    kind: deliveredEventType,
+    runId,
+    occurredAt: event.occurredAt,
+    payload: { runId, messageId, boundary }
+  }))
+}
+
+/**
+ * Expands one projected entry into itself plus any deliveries it discloses.
+ *
+ * @param event the projected journal entry
+ * @category projections
+ * @since 0.1.0
+ */
+export const expand = (event: ControlEvent): ReadonlyArray<ControlEvent> => [event, ...derive(event)]

package/src/SystemFlows.ts

@@ -0,0 +1,225 @@
+/**
+ * Reserved system-flow identifiers projected by the command-line interface.
+ *
+ * @since 0.1.0
+ */
+
+/**
+ * The projection metadata for one reserved system flow.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface SystemFlowEntry {
+  readonly verb: string
+  readonly flowId: `system/${string}`
+  readonly projection: "procedure" | "systemFlow"
+  readonly deployClass: boolean
+  readonly planBearing: boolean
+  /**
+   * Whether a control plane may plan and run this reserved id.
+   *
+   * `false` means the row is command-line metadata and nothing else: the verb
+   * is named here so the binary can refuse it by name, and no runtime may
+   * offer it as a flow. `replay` was removed by the frozen rc.0 contract yet
+   * every runtime turned the whole catalog into plannable flows, so
+   * `plan({flowId: "system/replay"})` returned a real approval card and only a
+   * later `run` failed. A removed feature that half works is exactly what the
+   * contract forbids.
+   */
+  readonly plannable: boolean
+}
+
+/**
+ * The authoritative command-line verb to reserved-flow map.
+ *
+ * `gc` is the retention verb: it resolves `@smthrs/engine-store`'s `retain`
+ * operation, which deletes aged terminal runs with their attempts, clock
+ * deadlines, deferred completions, journal entries, and time-travel archive
+ * rows. It is a procedure rather than a deploy-class system flow because it
+ * takes no plan and bears no approval envelope; the deletion is gated by the
+ * operator invoking it, and automatic retention stays opt-in.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const catalog = [
+  {
+    verb: "plan",
+    flowId: "system/plan",
+    projection: "procedure",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "run",
+    flowId: "system/run",
+    projection: "procedure",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "release",
+    flowId: "system/release",
+    projection: "systemFlow",
+    deployClass: true,
+    planBearing: true,
+    plannable: true
+  },
+  {
+    verb: "serve",
+    flowId: "system/serve",
+    projection: "systemFlow",
+    deployClass: true,
+    planBearing: true,
+    plannable: true
+  },
+  { verb: "up", flowId: "system/up", projection: "systemFlow", deployClass: true, planBearing: true, plannable: true },
+  { verb: "ls", flowId: "system/ls", projection: "procedure", deployClass: false, planBearing: false, plannable: true },
+  { verb: "ps", flowId: "system/ps", projection: "procedure", deployClass: false, planBearing: false, plannable: true },
+  {
+    verb: "logs",
+    flowId: "system/logs",
+    projection: "procedure",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "status",
+    flowId: "system/status",
+    projection: "procedure",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "cancel",
+    flowId: "system/cancel",
+    projection: "procedure",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "approve",
+    flowId: "system/approve",
+    projection: "procedure",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "deny",
+    flowId: "system/deny",
+    projection: "procedure",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "signal",
+    flowId: "system/signal",
+    projection: "procedure",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  { verb: "gc", flowId: "system/gc", projection: "procedure", deployClass: false, planBearing: false, plannable: true },
+  {
+    verb: "replay",
+    flowId: "system/replay",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: false,
+    plannable: false
+  },
+  {
+    verb: "add",
+    flowId: "system/add",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: true,
+    plannable: true
+  },
+  {
+    verb: "remove",
+    flowId: "system/remove",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: true,
+    plannable: true
+  },
+  {
+    verb: "eject",
+    flowId: "system/eject",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: true,
+    plannable: true
+  },
+  {
+    verb: "test",
+    flowId: "system/test",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "init",
+    flowId: "system/init",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: true,
+    plannable: true
+  },
+  {
+    verb: "doctor",
+    flowId: "system/doctor",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  },
+  {
+    verb: "migrate",
+    flowId: "system/migrate",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: true,
+    plannable: true
+  },
+  {
+    // A build target declaring `approval: "required"`: its plan input is the
+    // target's label and revision digest, and the build planner runs it only
+    // once that plan is approved. The build executes it, never a control run.
+    verb: "target",
+    flowId: "system/target",
+    projection: "systemFlow",
+    deployClass: true,
+    planBearing: true,
+    plannable: true
+  },
+  {
+    verb: "docs",
+    flowId: "system/docs",
+    projection: "systemFlow",
+    deployClass: false,
+    planBearing: false,
+    plannable: true
+  }
+] as const satisfies ReadonlyArray<SystemFlowEntry>
+
+/**
+ * The catalog entries a control runtime may offer as flows.
+ *
+ * One list, so a composition that builds its own flow map (the CLI does) and
+ * the runtimes' own defaults cannot disagree about which reserved ids exist.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const plannable: ReadonlyArray<SystemFlowEntry> = catalog.filter((entry) => entry.plannable)

package/src/WebCryptoCipher.ts

@@ -0,0 +1,169 @@
+/**
+ * AES-256-GCM credential encryption over the Web Crypto API.
+ *
+ * One adapter serves both hosts the project supports: `globalThis.crypto.subtle`
+ * is the browser's own API and has been Node's since v19, so this module
+ * imports nothing from `node:*` and still runs unmodified on the server. A host
+ * without Web Crypto, such as an old runtime or a locked-down worker, fails
+ * with the typed `Unavailable`, never a defect. A key that is not 32
+ * base64-encoded bytes fails with `InvalidInput`. A record that does not open
+ * fails with `PersistenceError` on operation `credential.open`, which names
+ * whether the stored nonce was malformed or the ciphertext failed
+ * authentication (a different key, changed metadata, or tampered bytes).
+ *
+ * The key is host-managed and supplied at layer construction. It is held as a
+ * non-extractable `CryptoKey`, so it cannot be read back out of the cipher, and
+ * it never reaches `CredentialStore`.
+ *
+ * @since 0.1.0
+ */
+
+import { canonicalize } from "@smthrs/canonical"
+import { Effect, Layer, Redacted } from "effect"
+import { InvalidInput, PersistenceError, type Unavailable } from "./ControlError.ts"
+import * as CredentialCipher from "./CredentialCipher.ts"
+
+const algorithm = "AES-GCM"
+const nonceBytes = 12
+const contextFormatVersion = 1
+
+const toBase64 = (bytes: Uint8Array): string => {
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+}
+
+const fromBase64 = (value: string): Uint8Array<ArrayBuffer> => {
+  const binary = atob(value)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index)
+  return bytes
+}
+
+const subtle = (): Effect.Effect<SubtleCrypto, Unavailable> =>
+  Effect.suspend(() => {
+    const available = globalThis.crypto as Crypto | undefined
+    return available?.subtle === undefined
+      ? Effect.fail(CredentialCipher.unavailable())
+      : Effect.succeed(available.subtle)
+  })
+
+const randomNonce = (): Effect.Effect<Uint8Array<ArrayBuffer>, Unavailable> =>
+  Effect.suspend(() => {
+    const available = globalThis.crypto as Crypto | undefined
+    return available?.getRandomValues === undefined
+      ? Effect.fail(CredentialCipher.unavailable())
+      : Effect.succeed(available.getRandomValues(new Uint8Array(nonceBytes)))
+  })
+
+const encodeContext = (context: CredentialCipher.Context): Effect.Effect<Uint8Array<ArrayBuffer>, Unavailable> =>
+  Effect.try({
+    try: () => {
+      // Canonical JSON names and escapes each field, so embedded delimiters
+      // cannot make two metadata tuples authenticate as the same bytes. The
+      // explicit format version makes a future byte contract distinguishable.
+      const document = canonicalize({
+        formatVersion: contextFormatVersion,
+        id: context.id,
+        name: context.name,
+        version: context.version
+      })
+      return new TextEncoder().encode(document)
+    },
+    catch: CredentialCipher.unavailable
+  })
+
+const invalidKey = (): InvalidInput => new InvalidInput({ issue: "Credential key must be 32 base64-encoded bytes" })
+
+const unopenable = (reason: "malformed_nonce" | "authentication_failed", cause: unknown): PersistenceError =>
+  new PersistenceError({
+    operation: "credential.open",
+    message: reason === "malformed_nonce"
+      ? "Stored credential nonce is malformed"
+      : "Credential failed authentication: a different key, changed metadata, or tampered ciphertext",
+    cause
+  })
+
+/**
+ * Host-managed key material for the cipher.
+ *
+ * `key` is 32 raw bytes, base64-encoded, held redacted so it cannot be printed
+ * or serialized by accident.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+  readonly key: Redacted.Redacted<string>
+}
+
+/**
+ * Imports the host key and constructs the cipher.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options: Options): Effect.Effect<CredentialCipher.Service, Unavailable | InvalidInput> =>
+  Effect.gen(function*() {
+    const crypto = yield* subtle()
+    const raw = yield* Effect.try({
+      try: () => fromBase64(Redacted.value(options.key)),
+      catch: invalidKey
+    })
+    if (raw.length !== 32) return yield* Effect.fail(invalidKey())
+    const key = yield* Effect.tryPromise({
+      try: () => crypto.importKey("raw", raw, algorithm, false, ["encrypt", "decrypt"]),
+      catch: CredentialCipher.unavailable
+    })
+
+    return CredentialCipher.make({
+      seal: Effect.fn("WebCryptoCipher.seal")(function*(plaintext, context) {
+        const additionalData = yield* encodeContext(context)
+        const nonce = yield* randomNonce()
+        const ciphertext = yield* Effect.tryPromise({
+          try: () =>
+            crypto.encrypt(
+              { name: algorithm, iv: nonce, additionalData: additionalData },
+              key,
+              new TextEncoder().encode(Redacted.value(plaintext))
+            ),
+          catch: CredentialCipher.unavailable
+        })
+        return { ciphertext: toBase64(new Uint8Array(ciphertext)), nonce: toBase64(nonce) }
+      }),
+      open: Effect.fn("WebCryptoCipher.open")(function*(sealed, context) {
+        const additionalData = yield* encodeContext(context)
+        const plaintext = yield* Effect.try({
+          try: () => fromBase64(sealed.nonce),
+          catch: (cause) => unopenable("malformed_nonce", cause)
+        }).pipe(
+          Effect.flatMap((nonce) =>
+            Effect.tryPromise({
+              try: () =>
+                crypto.decrypt(
+                  { name: algorithm, iv: nonce, additionalData: additionalData },
+                  key,
+                  fromBase64(sealed.ciphertext)
+                ),
+              catch: (cause) => unopenable("authentication_failed", cause)
+            })
+          ),
+          Effect.tapError((error) =>
+            Effect.logWarning({ message: error.message, operation: error.operation, credentialId: context.id })
+          )
+        )
+        return Redacted.make(new TextDecoder().decode(plaintext))
+      })
+    })
+  })
+
+/**
+ * Provides AES-256-GCM credential encryption under a host-managed key.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (
+  options: Options
+): Layer.Layer<CredentialCipher.CredentialCipher, Unavailable | InvalidInput> =>
+  Layer.effect(CredentialCipher.CredentialCipher)(make(options))