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

package/src/ControlServer.ts

@@ -0,0 +1,182 @@
+/**
+ * RPC server layers for the control service.
+ *
+ * @since 0.1.0
+ */
+
+import { Cause, Effect, Layer, Stream } from "effect"
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http"
+import { RpcServer } from "effect/unstable/rpc"
+import { Control } from "./Control.ts"
+import { Unauthorized } from "./ControlError.ts"
+import { ControlPrincipal, ControlRpcs, RunVisibility } from "./ControlRpcs.ts"
+
+/**
+ * Logs the raw defect of a failed RPC handler on the server, and nothing for
+ * a typed failure or an interruption. `ControlRpcs.ControlDefect` sends
+ * clients only the designed sentence, so this log is where the detail lives.
+ * Pass it to `Effect.tapCause` or `Stream.tapCause` around a handler.
+ *
+ * @category logging
+ * @since 1.0.0
+ */
+export const logDefect = (cause: Cause.Cause<unknown>): Effect.Effect<void> =>
+  Cause.hasDies(cause) ? Effect.logError("A control RPC handler died", cause) : Effect.void
+
+const logged = <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.tapCause(effect, logDefect)
+
+/**
+ * Control RPC handlers delegating to the transport-independent service.
+ *
+ * Every mutation that records who asked reads `ControlPrincipal` and stamps
+ * it, rather than forwarding whatever the client sent. The identity the
+ * middleware authenticated is the only one the server can stand behind, and it
+ * is what reaches the journal, `RunSummary.cancellation`, and a steer's
+ * notification provenance.
+ *
+ * `List`, `Watch` and every run mutation read it too: a principal
+ * `ControlRpcs.RunVisibility` does not make an operator reads and mutates only
+ * the runs it launched; any other run answers `RunNotFound`.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = ControlRpcs.toLayer(
+  Effect.gen(function*() {
+    const control = yield* Control
+    // A reader that is not an operator is restricted to the runs its own
+    // principal launched. `reader` is not on the wire, so only this stamp sets
+    // it. The authentication middleware provides the rule with the principal.
+    const reader = Effect.gen(function*() {
+      const principal = yield* ControlPrincipal
+      const visibility = yield* RunVisibility
+      return visibility.seesAllRuns(principal) ? {} : { reader: principal }
+    })
+    return ControlRpcs.of({
+      Plan: Effect.fn("Control.plan")((input) => control.plan(input), logged),
+      Run: Effect.fn("Control.run")((input) =>
+        Effect.gen(function*() {
+          const principal = yield* ControlPrincipal
+          return yield* control.run({ ...input, principal })
+        }), logged),
+      Approve: Effect.fn("Control.approve")((input) =>
+        Effect.gen(function*() {
+          const principal = yield* ControlPrincipal
+          if (principal.id === "loopback" && principal.kind === "anonymous") {
+            return yield* new Unauthorized({ message: "An operator credential is required" })
+          }
+          return yield* control.approve({ ...input, principal })
+        }), logged),
+      Deny: Effect.fn("Control.deny")((input) =>
+        Effect.gen(function*() {
+          const principal = yield* ControlPrincipal
+          if (principal.id === "loopback" && principal.kind === "anonymous") {
+            return yield* new Unauthorized({ message: "An operator credential is required" })
+          }
+          return yield* control.deny({ ...input, principal })
+        }), logged),
+      Steer: Effect.fn("Control.steer")((input) =>
+        Effect.gen(function*() {
+          const principal = yield* ControlPrincipal
+          // A steer carries a principal on the wire because an in-process
+          // caller names one that is not an operator: `agent/send` attributes
+          // a child's steer to the parent flow. A remote client may not, so
+          // the authenticated identity replaces whatever arrived. It reaches
+          // the notification's `sourceActor` and the run transcript, which is
+          // exactly where a spoofed name would be read as truth.
+          const { attribution: _attribution, ...message } = input.message
+          return yield* control.steer({ ...input, message: { ...message, principal }, ...yield* reader })
+        }), logged),
+      Signal: Effect.fn("Control.signal")((input) =>
+        Effect.gen(function*() {
+          const principal = yield* ControlPrincipal
+          return yield* control.signal({ ...input, principal, ...yield* reader })
+        }), logged),
+      Cancel: Effect.fn("Control.cancel")((input) =>
+        Effect.gen(function*() {
+          const principal = yield* ControlPrincipal
+          return yield* control.cancel({ ...input, principal, ...yield* reader })
+        }), logged),
+      Resume: Effect.fn("Control.resume")((input) =>
+        Effect.gen(function*() {
+          const principal = yield* ControlPrincipal
+          return yield* control.resume({ ...input, principal, ...yield* reader })
+        }), logged),
+      List: Effect.fn("Control.list")(
+        (input) => Effect.flatMap(reader, (restriction) => control.list({ ...input, ...restriction })),
+        logged
+      ),
+      Watch: (input) =>
+        Stream.tapCause(
+          Stream.unwrap(Effect.map(reader, (restriction) => control.watch({ ...input, ...restriction }))),
+          logDefect
+        )
+    })
+  })
+)
+
+/**
+ * Whether a request's `Origin` may reach the control mounts.
+ *
+ * Non-browser clients send no `Origin`. A browser always sends one, on POST
+ * and on the WebSocket upgrade, and a cross-site page cannot forge it. Refusing
+ * any `Origin` whose authority differs from `Host` stops a page on another site
+ * from riding a credential that a proxy or cookie attaches on the victim's
+ * behalf (cross-site WebSocket hijacking of the `Watch` stream).
+ */
+const sameOrigin = (headers: Readonly<Record<string, string>>): boolean => {
+  const origin = headers.origin
+  if (origin === undefined) return true
+  const host = headers.host
+  const parsed = URL.parse(origin)
+  return host !== undefined && parsed !== null &&
+    (parsed.protocol === "http:" || parsed.protocol === "https:") &&
+    parsed.origin === origin && parsed.host === host.toLowerCase()
+}
+
+/**
+ * Route middleware on the two control mounts only, so the router's own path
+ * matching decides what it guards, and a host's stricter global policy (the
+ * gateway's ingress) still answers first with its own typed refusal.
+ */
+const originGuard = HttpRouter.middleware((httpEffect) =>
+  Effect.gen(function*() {
+    const request = yield* HttpServerRequest.HttpServerRequest
+    if (sameOrigin(request.headers)) return yield* httpEffect
+    return HttpServerResponse.text("The browser Origin must match the control server Host", { status: 403 })
+  })
+).layer
+
+const server = RpcServer.layer(ControlRpcs, {
+  disableFatalDefects: true
+})
+
+const http = server.pipe(
+  Layer.provide(layer),
+  Layer.provideMerge(RpcServer.layerProtocolHttp({ path: "/rpc" }).pipe(Layer.provide(originGuard))),
+  Layer.fresh
+)
+
+const websocket = server.pipe(
+  Layer.provide(layer),
+  Layer.provideMerge(RpcServer.layerProtocolWebsocket({ path: "/rpc/ws" }).pipe(Layer.provide(originGuard))),
+  Layer.fresh
+)
+
+/**
+ * Mounts control RPC on the ambient `HttpRouter`: unary procedures over POST
+ * `/rpc` and the `watch` stream over WebSocket `/rpc/ws`. Both protocols are
+ * mounted together because `ControlClient` projects the same `Control` vtable
+ * across the two transports.
+ *
+ * A request carrying a browser `Origin` that does not match its `Host` is
+ * refused with 403 before authentication, so a page on another site cannot
+ * open the socket or post to `/rpc` with a credential a proxy attaches.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerHttp = Layer.mergeAll(
+  http,
+  websocket
+)

package/src/Credential.ts

@@ -0,0 +1,310 @@
+/**
+ * Credential storage boundary.
+ *
+ * Credentials are capabilities. They must never enter flow input, plan
+ * digests, journal payloads, or model context, so only a {@link CredentialRef}
+ * — an id and a human-readable connection name — crosses the browser-safe
+ * contract. Plaintext exists in exactly two places: inside a `Redacted` handed
+ * to `create`/`rotate`, and inside the `Redacted` returned by `resolve`.
+ *
+ * The implementation composes two ports:
+ *
+ * - {@link CredentialStore} persists an opaque sealed record and enforces
+ *   compare-and-set on writes, so concurrent rotations cannot interleave.
+ *   `rotate` with `expected` extends that compare to the secret itself: the
+ *   secret it checks and the version it writes over come from one read, so a
+ *   writer that commits in between, in any process, is refused.
+ * - {@link CredentialCipher} seals and opens the secret under host-managed
+ *   keys. `WebCryptoCipher` is the browser and Node adapter; a host with no
+ *   secure key material fails with the typed `Unavailable`.
+ *
+ * Authorization is a host decision, injected as {@link Options.authorize}. A
+ * reference is also authenticated on every operation: caller-owned fields are
+ * snapshotted before policy effects run, and a caller cannot present a forged
+ * or stale `CredentialRef` because the snapshotted name must still match the
+ * stored record.
+ *
+ * @since 0.1.0
+ */
+
+import { Context, Effect, Layer, Option, Redacted } from "effect"
+import { CredentialConflict, InvalidInput, type PersistenceError, Unauthorized, Unavailable } from "./ControlError.ts"
+import * as CredentialCipher from "./CredentialCipher.ts"
+import * as CredentialStore from "./CredentialStore.ts"
+
+// String.prototype.isWellFormed without the ES2024 lib, which every package
+// compiling this source would also need. A loop, not a regex: a match would
+// leave the rejected secret in the legacy RegExp.input static.
+const wellFormed = (value: string): boolean => {
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index)
+    if (unit >= 0xdc00 && unit <= 0xdfff) return false
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const low = value.charCodeAt(++index)
+      if (!(low >= 0xdc00 && low <= 0xdfff)) return false
+    }
+  }
+  return true
+}
+
+/**
+ * A journal-safe name for a stored connection credential.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface CredentialRef {
+  readonly id: string
+  readonly name: string
+}
+
+/**
+ * One credential operation, as seen by a host authorization policy.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Operation = "list" | "get" | "create" | "resolve" | "rotate" | "revoke"
+
+/**
+ * How {@link Credential.rotate} compares before it writes.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface RotateOptions {
+  /** The secret the caller last saw; the rotation commits only over it. */
+  readonly expected?: Redacted.Redacted<string> | undefined
+}
+
+/**
+ * Adapter-bound credential resolution. References are safe to list and
+ * persist; only `resolve` crosses into a secret-bearing adapter boundary.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Credential {
+  readonly list: () => Effect.Effect<ReadonlyArray<CredentialRef>, Unavailable | Unauthorized>
+  readonly get: (id: string) => Effect.Effect<CredentialRef, Unavailable | Unauthorized>
+  readonly create: (
+    options: { readonly id: string; readonly name: string; readonly secret: Redacted.Redacted<string> }
+  ) => Effect.Effect<CredentialRef, Unavailable | Unauthorized | CredentialConflict | InvalidInput>
+  readonly resolve: (
+    reference: CredentialRef
+  ) => Effect.Effect<Redacted.Redacted<string>, Unavailable | Unauthorized | PersistenceError>
+  /**
+   * Replaces the secret. With `expected`, replaces it only while the stored
+   * secret still equals `expected`, and otherwise fails `CredentialConflict`
+   * at the stored version without writing.
+   */
+  readonly rotate: (
+    reference: CredentialRef,
+    secret: Redacted.Redacted<string>,
+    options?: RotateOptions | undefined
+  ) => Effect.Effect<
+    CredentialRef,
+    Unavailable | Unauthorized | CredentialConflict | InvalidInput | PersistenceError
+  >
+  readonly revoke: (reference: CredentialRef) => Effect.Effect<void, Unavailable | Unauthorized>
+}
+
+/**
+ * Service tag for credential resolution.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export const Credential: Context.Service<Credential, Credential> = Context.Service("/control/Credential")
+
+const unavailable = (): Unavailable =>
+  new Unavailable({
+    feature: "credential storage",
+    ticket: "control-credential-storage"
+  })
+
+/**
+ * A credential implementation that explicitly reports unavailable storage.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = (): Credential =>
+  Credential.of({
+    list: Effect.fn("Credential.list")(() => Effect.fail(unavailable())),
+    get: Effect.fn("Credential.get")(() => Effect.fail(unavailable())),
+    create: Effect.fn("Credential.create")(() => Effect.fail(unavailable())),
+    resolve: Effect.fn("Credential.resolve")(() => Effect.fail(unavailable())),
+    rotate: Effect.fn("Credential.rotate")(() => Effect.fail(unavailable())),
+    revoke: Effect.fn("Credential.revoke")(() => Effect.fail(unavailable()))
+  })
+
+/**
+ * Layer for the unavailable credential-storage boundary.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = Layer.succeed(Credential, makeNoop())
+
+/**
+ * The collaborators a working credential boundary needs.
+ *
+ * `authorize` is the host's policy hook. It defaults to allowing every
+ * operation, which is correct for a single-principal local process; a server
+ * composition supplies its own and gets typed `Unauthorized` failures for free.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+  readonly store: CredentialStore.Service
+  readonly cipher: CredentialCipher.Service
+  readonly authorize?:
+    | ((operation: Operation, reference: Option.Option<CredentialRef>) => Effect.Effect<void, Unauthorized>)
+    | undefined
+}
+
+const referenceOf = (value: { readonly id: string; readonly name: string }): CredentialRef =>
+  Object.freeze({
+    id: value.id,
+    name: value.name
+  })
+
+const cipherContextOf = (
+  value: { readonly id: string; readonly name: string; readonly version: number }
+): CredentialCipher.Context =>
+  Object.freeze({
+    id: value.id,
+    name: value.name,
+    version: value.version
+  })
+
+const missing = (id: string): Unauthorized =>
+  // Deliberately indistinguishable from a denied reference: telling an
+  // unauthorized caller which ids exist is itself a leak.
+  new Unauthorized({ message: `Credential ${id} is not available to this caller` })
+
+/**
+ * Constructs a working credential boundary over a store and a cipher.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options: Options): Credential => {
+  const authorize = options.authorize ?? (() => Effect.void)
+  const store = options.store
+  const cipher = options.cipher
+
+  /** Reads the record `reference` names, refusing a forged or stale one. */
+  const authenticate = (
+    operation: Operation,
+    reference: CredentialRef
+  ): Effect.Effect<CredentialStore.SealedRecord, Unavailable | Unauthorized> =>
+    Effect.gen(function*() {
+      const snapshot = referenceOf(reference)
+      yield* authorize(operation, Option.some(snapshot))
+      const record = yield* store.read(snapshot.id)
+      if (Option.isNone(record)) return yield* Effect.fail(missing(snapshot.id))
+      if (record.value.name !== snapshot.name) return yield* Effect.fail(missing(snapshot.id))
+      return record.value
+    })
+
+  const put = (
+    record: CredentialStore.SealedRecord,
+    secret: Redacted.Redacted<string>
+  ): Effect.Effect<CredentialRef, Unavailable | CredentialConflict | InvalidInput> =>
+    Effect.gen(function*() {
+      if (!wellFormed(Redacted.value(secret))) {
+        return yield* Effect.fail(new InvalidInput({ issue: "Credential secret must be well-formed Unicode" }))
+      }
+      // The metadata written beside this blob is also its authenticated data;
+      // moving the blob to another id, name, or version must make it unreadable.
+      const context = cipherContextOf(record)
+      const sealed = yield* cipher.seal(secret, context)
+      const now = yield* Effect.clockWith((clock) => clock.currentTimeMillis)
+      yield* store.write({ ...record, ...sealed, updatedAtMs: now })
+      return referenceOf(record)
+    })
+
+  return Credential.of({
+    list: Effect.fn("Credential.list")(function*() {
+      yield* authorize("list", Option.none())
+      const records = yield* store.list()
+      return records.map(referenceOf)
+    }),
+    get: Effect.fn("Credential.get")(function*(id) {
+      const record = yield* store.read(id)
+      if (Option.isNone(record)) return yield* Effect.fail(missing(id))
+      const reference = referenceOf(record.value)
+      yield* authorize("get", Option.some(reference))
+      return reference
+    }),
+    create: Effect.fn("Credential.create")(function*(input) {
+      const snapshot = Object.freeze({
+        reference: referenceOf(input),
+        secret: input.secret
+      })
+      yield* authorize("create", Option.some(snapshot.reference))
+      return yield* put(
+        {
+          id: snapshot.reference.id,
+          name: snapshot.reference.name,
+          ciphertext: "",
+          nonce: "",
+          version: 1,
+          updatedAtMs: 0
+        },
+        snapshot.secret
+      )
+    }),
+    resolve: Effect.fn("Credential.resolve")(function*(reference) {
+      const record = yield* authenticate("resolve", reference)
+      return yield* cipher.open(
+        { ciphertext: record.ciphertext, nonce: record.nonce },
+        cipherContextOf(record)
+      )
+    }),
+    rotate: Effect.fn("Credential.rotate")(function*(reference, secret, options) {
+      const expected = options?.expected
+      const record = yield* authenticate("rotate", reference)
+      if (expected !== undefined) {
+        const stored = yield* cipher.open(
+          { ciphertext: record.ciphertext, nonce: record.nonce },
+          cipherContextOf(record)
+        )
+        if (Redacted.value(stored) !== Redacted.value(expected)) {
+          return yield* Effect.fail(
+            new CredentialConflict({ id: record.id, expectedVersion: record.version, actualVersion: record.version })
+          )
+        }
+      }
+      // `put` writes over exactly the version read above, so the secret just
+      // compared is still the stored one when the write commits.
+      return yield* put({ ...record, version: record.version + 1 }, secret)
+    }),
+    revoke: Effect.fn("Credential.revoke")(function*(reference) {
+      const record = yield* authenticate("revoke", reference)
+      yield* store.remove(record.id)
+    })
+  })
+}
+
+/**
+ * Provides a working credential boundary over the ambient store and cipher.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (
+  options: { readonly authorize?: Options["authorize"] } = {}
+): Layer.Layer<
+  Credential,
+  never,
+  CredentialStore.CredentialStore | CredentialCipher.CredentialCipher
+> =>
+  Layer.effect(Credential)(Effect.gen(function*() {
+    const store = yield* CredentialStore.CredentialStore
+    const cipher = yield* CredentialCipher.CredentialCipher
+    return make({ store, cipher, ...(options.authorize === undefined ? {} : { authorize: options.authorize }) })
+  }))

package/src/CredentialCipher.ts

@@ -0,0 +1,110 @@
+/**
+ * Browser-safe encryption port for credential material.
+ *
+ * The cipher is the only place plaintext exists outside a `Redacted`. Keys are
+ * host-managed: an adapter receives a key from its host and never persists one
+ * through {@link CredentialStore}, so a stolen store is ciphertext and nothing
+ * else.
+ *
+ * @since 0.1.0
+ */
+
+import { Context as EffectContext, Effect, Layer, type Redacted } from "effect"
+import { type PersistenceError, Unavailable } from "./ControlError.ts"
+
+/**
+ * One encrypted secret: base64 ciphertext and the nonce it was sealed under.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Sealed {
+  readonly ciphertext: string
+  readonly nonce: string
+}
+
+/**
+ * Credential metadata authenticated with one sealed secret.
+ *
+ * Every field is immutable because the same values must be written beside the
+ * ciphertext and supplied again when it is opened.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Context {
+  readonly id: string
+  readonly name: string
+  readonly version: number
+}
+
+/**
+ * Authenticated encryption over credential plaintext.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Service {
+  readonly seal: (plaintext: Redacted.Redacted<string>, context: Context) => Effect.Effect<Sealed, Unavailable>
+  /**
+   * Fails with `PersistenceError` on operation `credential.open` when the
+   * record does not open: a malformed nonce, or ciphertext that fails
+   * authentication under this key and context.
+   */
+  readonly open: (
+    sealed: Sealed,
+    context: Context
+  ) => Effect.Effect<Redacted.Redacted<string>, Unavailable | PersistenceError>
+}
+
+/**
+ * Service key for credential encryption.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class CredentialCipher extends EffectContext.Service<CredentialCipher, Service>()(
+  "/control/CredentialCipher"
+) {}
+
+/**
+ * Constructs a cipher from an implementation record.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (implementation: Service): Service => CredentialCipher.of(implementation)
+
+/**
+ * The typed failure a host reports when no secure key material is reachable.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const unavailable = (): Unavailable =>
+  new Unavailable({
+    feature: "credential encryption",
+    ticket: "control-credential-storage"
+  })
+
+/**
+ * A cipher that reports unavailable key material for every operation.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = (overrides: Partial<Service> = {}): Service =>
+  make({
+    seal: Effect.fn("CredentialCipher.seal")(() => Effect.fail(unavailable())),
+    open: Effect.fn("CredentialCipher.open")(() => Effect.fail(unavailable())),
+    ...overrides
+  })
+
+/**
+ * Provides a cipher that reports unavailable key material.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = (overrides: Partial<Service> = {}): Layer.Layer<CredentialCipher> =>
+  Layer.succeed(CredentialCipher)(makeNoop(overrides))