@akterjs/effect 0.0.0-stage → 0.1.0

package/src/host/actor/actor-database.service.ts

@@ -0,0 +1,145 @@
+import { Context, Effect, Layer, Option } from "effect";
+import type { Scope } from "effect";
+import type { SqlClient } from "effect/sql";
+
+import type { HostedActor } from "#src/contract/actor/actor.contract";
+import type { FileStorage } from "#src/contract/file/actor-files.contract";
+import { actorFileStorage, emptyFileStorage, unavailableFileStorage } from "#src/host/file/actor-file-storage.sql";
+import { LocalBlobHomes } from "#src/host/file/local-blob-home.service";
+import { localActorFiles } from "#src/host/file/local-blob-owner.sql";
+import type { LocalActorFileOpener, LocalActorFiles } from "#src/host/file/local-blob-owner.sql";
+import { replayFileStorage } from "#src/host/file/replay-file-storage.sql";
+import { ActorMigrations } from "#src/host/migration/actor-migrations.service";
+import type { ActorOpenError as MigrationOpenError } from "#src/host/migration/actor-migrations.service";
+import { SqliteDriver } from "#src/host/sqlite/sqlite-driver.service";
+
+interface OpenOptions {
+  readonly actor: HostedActor;
+  readonly filename: string;
+  readonly identity?: string;
+}
+
+interface OpenedActor {
+  readonly actor: HostedActor;
+  readonly files: (sql: SqlClient.SqlClient) => FileStorage;
+  readonly filename: string;
+  readonly fileSession?: LocalActorFiles;
+  readonly reader: SqlClient.SqlClient;
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface ReplayOptions {
+  readonly actor: HostedActor;
+  readonly source: SqlClient.SqlClient;
+}
+
+type Clients = Effect.Success<ReturnType<SqliteDriver["Service"]["openActor"]>>;
+
+type ClientsFailure = Effect.Error<ReturnType<SqliteDriver["Service"]["openActor"]>>;
+
+interface Opening {
+  readonly reader: Clients["reader"];
+  readonly session: LocalActorFileOpener;
+}
+
+const memory = ":memory:";
+
+const queryOnly = "PRAGMA query_only = ON";
+
+const unavailableFiles = (): FileStorage => unavailableFileStorage;
+
+const emptyFiles = (): FileStorage => emptyFileStorage;
+
+type ActorOpenError = MigrationOpenError | ClientsFailure | Effect.Error<ReturnType<LocalActorFileOpener>>;
+
+const clientsOf = (
+  driver: SqliteDriver["Service"],
+  { filename, identity }: OpenOptions,
+): Effect.Effect<Clients, ClientsFailure, Scope.Scope> =>
+  Option.match(Option.fromNullishOr(identity), {
+    onNone: () => Effect.map(driver.open(filename), (sql) => ({ reader: driver.openQueryOnly(filename), sql })),
+    onSome: (actor) => driver.openActor({ actor, filename }),
+  });
+
+const openedWith = Effect.fnUntraced(function* openedWith(
+  { reader: opening, session }: Opening,
+  { actor, filename, identity }: OpenOptions,
+  sql: SqlClient.SqlClient,
+) {
+  if (filename === memory) {
+    return { actor, filename, files: unavailableFiles, reader: sql, sql };
+  }
+
+  const reader = yield* opening;
+
+  const prepared = yield* Option.match(Option.fromNullishOr(identity), {
+    onNone: () => Effect.succeedNone,
+    onSome: (owner) => session({ actor: owner, sql }),
+  });
+
+  const files = (connection: SqlClient.SqlClient): FileStorage =>
+    Option.match(prepared, {
+      onNone: () => unavailableFileStorage,
+      onSome: ({ home, owner }) => actorFileStorage({ actor: owner.actor, open: home.transfers.open, sql: connection }),
+    });
+
+  return {
+    actor,
+    filename,
+    files,
+    reader,
+    sql,
+    ...Option.match(prepared, { onNone: () => ({}), onSome: (fileSession) => ({ fileSession }) }),
+  };
+});
+
+export class ActorDatabase extends Context.Service<
+  ActorDatabase,
+  {
+    readonly blank: (actor: HostedActor) => Effect.Effect<OpenedActor, MigrationOpenError, Scope.Scope>;
+    readonly open: (options: OpenOptions) => Effect.Effect<OpenedActor, ActorOpenError, Scope.Scope>;
+    /** Opens a database file that is no actor's yet, such as a fork's staged copy: no migrations, no files. */
+    readonly openCopy: (filename: string) => Effect.Effect<SqlClient.SqlClient, ClientsFailure, Scope.Scope>;
+    readonly replay: (options: ReplayOptions) => Effect.Effect<OpenedActor, ActorOpenError, Scope.Scope>;
+  }
+>()("@akterjs/effect/host/actor/actor-database.service/ActorDatabase", {
+  make: Effect.gen(function* makeActorDatabase() {
+    const driver = yield* SqliteDriver;
+    const migrations = yield* ActorMigrations;
+    const homes = yield* Effect.serviceOption(LocalBlobHomes);
+    const session = localActorFiles(homes);
+    const replayFiles = replayFileStorage(homes);
+
+    const open = Effect.fn("ActorDatabase.open")(function* open(options: OpenOptions) {
+      const { reader, sql } = yield* clientsOf(driver, options);
+
+      yield* migrations.prepare({ actor: options.actor, sql });
+
+      return yield* openedWith({ reader, session }, options, sql);
+    });
+
+    const blank = Effect.fn("ActorDatabase.blank")(function* blank(actor: HostedActor) {
+      const { reader, sql } = yield* driver.openInMemory;
+
+      yield* migrations.prepare({ actor, sql });
+      yield* reader.unsafe(queryOnly);
+
+      const files = Option.match(homes, { onNone: () => unavailableFiles, onSome: () => emptyFiles });
+
+      return { actor, filename: memory, files, reader, sql: reader };
+    });
+
+    const replay = Effect.fn("ActorDatabase.replay")(function* replay({ actor, source }: ReplayOptions) {
+      const initial = yield* open({ actor, filename: memory });
+
+      return yield* replayFiles(source, initial);
+    });
+
+    return { blank, open, openCopy: driver.open, replay } as const;
+  }),
+}) {
+  public static readonly layer = Layer.effect(this, this.make).pipe(Layer.provide(ActorMigrations.layer));
+  public static readonly layerNode = this.layer.pipe(Layer.provide(SqliteDriver.layerNode));
+}
+
+export type { ActorOpenError, OpenedActor, OpenOptions };

package/src/host/actor/actor-exclusive.pure.ts

@@ -0,0 +1,32 @@
+import { Effect, Ref, Semaphore } from "effect";
+
+interface ActorExclusive {
+  readonly close: Effect.Effect<void>;
+  readonly run: <Success, Failure, Needs>(
+    effect: Effect.Effect<Success, Failure, Needs>,
+  ) => Effect.Effect<Success, Failure, Needs>;
+}
+
+const oneActorOperation = 1;
+
+const actorExclusive: Effect.Effect<ActorExclusive> = Effect.gen(function* makeActorExclusive() {
+  const semaphore = yield* Semaphore.make(oneActorOperation);
+  const closed = yield* Ref.make(false);
+
+  const run: ActorExclusive["run"] = (effect) =>
+    semaphore.withPermits(oneActorOperation)(
+      Effect.flatMap(Ref.get(closed), (disposed) => {
+        if (disposed) {
+          return Effect.die("the actor database scope is closed");
+        }
+
+        return effect;
+      }),
+    );
+
+  return { close: semaphore.withPermits(oneActorOperation)(Ref.set(closed, true)), run };
+});
+
+export { actorExclusive };
+
+export type { ActorExclusive };

package/src/host/actor/actor-records.sql.ts

@@ -0,0 +1,78 @@
+import { Array as Arr, Effect, Option, String as Str } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import type { HostedActor } from "#src/contract/actor/actor.contract";
+
+import type { AppliedMigration } from "#src/host/migration/migration-plan.pure";
+import type { ReservedObject } from "./reserved-names.pure.js";
+
+interface AppliedRow extends AppliedMigration {
+  readonly at: number;
+}
+
+interface Recording {
+  readonly row: AppliedRow;
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface Replacing {
+  readonly sql: SqlClient.SqlClient;
+  readonly value: string;
+}
+
+interface Upgrading {
+  readonly actor: HostedActor;
+  readonly sql: SqlClient.SqlClient;
+}
+
+type Rows<Row> = Effect.Effect<readonly Row[], SqlError.SqlError>;
+
+type Write = Effect.Effect<void, SqlError.SqlError>;
+
+const appliedMigrations = (sql: SqlClient.SqlClient): Rows<AppliedMigration> =>
+  sql`SELECT version, hash FROM akter_migrations ORDER BY version`;
+
+const recordMigration = ({ row, sql }: Recording): Write =>
+  Effect.asVoid(
+    sql`INSERT INTO akter_migrations (version, hash, applied_at) VALUES (${row.version}, ${row.hash}, ${row.at})`,
+  );
+
+interface SchemaObject extends ReservedObject {
+  readonly owner: string;
+}
+
+interface Reserving {
+  readonly prefixes: readonly string[];
+  readonly sql: SqlClient.SqlClient;
+}
+
+const reservedObjects = ({ prefixes, sql }: Reserving): Rows<ReservedObject> => {
+  const lowered = Arr.map(prefixes, Str.toLowerCase);
+
+  const reserved = (name: string): boolean =>
+    Arr.some(lowered, (prefix) => Str.startsWith(prefix)(Str.toLowerCase(name)));
+
+  return Effect.map(
+    sql<SchemaObject>`SELECT type, name, tbl_name AS owner, coalesce(sql, '') AS definition FROM sqlite_master ORDER BY type, name`,
+    Arr.filter((object) => reserved(object.name) || reserved(object.owner)),
+  );
+};
+
+const storedState = (sql: SqlClient.SqlClient): Rows<{ readonly value: string }> =>
+  sql`SELECT value FROM akter_state WHERE id = 1`;
+
+const replaceState = ({ sql, value }: Replacing): Write =>
+  Effect.asVoid(sql`UPDATE akter_state SET value = ${value} WHERE id = 1`);
+
+const upgradeStoredState = Effect.fnUntraced(function* upgradeStoredState({ actor, sql }: Upgrading) {
+  const rows = yield* storedState(sql);
+
+  const upgraded = yield* Option.match(Arr.head(rows), {
+    onNone: () => Effect.succeedNone,
+    onSome: (row) => actor.upgradeState(row.value),
+  });
+
+  yield* Option.match(upgraded, { onNone: () => Effect.void, onSome: (value) => replaceState({ sql, value }) });
+});
+
+export { appliedMigrations, recordMigration, reservedObjects, upgradeStoredState };

package/src/host/actor/reserved-name.errors.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+
+export class ReservedNameError extends Schema.TaggedError<ReservedNameError, { readonly brand: unique symbol }>()(
+  "ReservedNameError",
+  {
+    actor: Schema.String,
+    table: Schema.String,
+    version: Schema.Int,
+  },
+) {}

package/src/host/actor/reserved-names.pure.ts

@@ -0,0 +1,40 @@
+import { Array as Arr, Effect, Option } from "effect";
+
+import { ReservedNameError } from "./reserved-name.errors.js";
+
+interface ReservedObject {
+  readonly definition: string;
+  readonly name: string;
+  readonly type: string;
+}
+
+interface ReservedChange {
+  readonly actor: string;
+  readonly after: readonly ReservedObject[];
+  readonly before: readonly ReservedObject[];
+  readonly version: number;
+}
+
+const describeObject = (object: ReservedObject): string => `${object.type} ${object.name} ${object.definition}`;
+
+const missingFrom = (
+  objects: readonly ReservedObject[],
+  others: readonly ReservedObject[],
+): readonly ReservedObject[] => {
+  const kept = Arr.map(others, describeObject);
+
+  return Arr.filter(objects, (object) => !Arr.contains(kept, describeObject(object)));
+};
+
+const checkReserved = ({ actor, after, before, version }: ReservedChange): Effect.Effect<void, ReservedNameError> => {
+  const changed = Arr.appendAll(missingFrom(after, before), missingFrom(before, after));
+
+  return Option.match(Arr.head(changed), {
+    onNone: () => Effect.void,
+    onSome: (object) => Effect.fail(ReservedNameError.make({ actor, table: object.name, version })),
+  });
+};
+
+export { checkReserved };
+
+export type { ReservedObject };

package/src/host/actor/room.actor.ts

@@ -0,0 +1,57 @@
+import { Akter } from "@akterjs/effect/contract";
+import { FileAccessDeniedError } from "@akterjs/effect/contract/errors";
+import { Array as Arr, Effect } from "effect";
+
+import { NotMemberError, Room } from "#src/contract/room.contract";
+import type { Message } from "#src/contract/room.contract";
+
+const RoomLive = Room.toLayer({
+  commands: {
+    join: (room) =>
+      Effect.gen(function* join() {
+        const me = yield* Akter.principal;
+
+        yield* Room.update({ members: Arr.append(room.members, me.id) });
+      }),
+    post: (room, { text }) =>
+      Effect.gen(function* post() {
+        const me = yield* Akter.principal;
+
+        if (!Arr.contains(room.members, me.id)) {
+          return yield* NotMemberError.make({});
+        }
+
+        const id = yield* Akter.id;
+        const at = yield* Akter.now;
+        const sql = yield* Akter.sql;
+
+        yield* sql`INSERT INTO messages ${sql.insert({ at, author: me.id, id, text })}`;
+
+        return id;
+      }),
+  },
+  // A room's files are its members': anyone who joined may read and upload, and no one else.
+  files: {
+    authorize: (room, { access, path }) =>
+      Akter.principal.pipe(
+        Effect.filterOrFail(
+          (me) => Arr.contains(room.members, me.id),
+          () => FileAccessDeniedError.make({ access, message: "only the room's members may use its files", path }),
+        ),
+        Effect.asVoid,
+      ),
+  },
+  migrations: {
+    1: (sql) =>
+      sql`CREATE TABLE messages (id TEXT PRIMARY KEY, author TEXT NOT NULL, text TEXT NOT NULL, at INTEGER NOT NULL)`,
+  },
+  queries: {
+    messages: (_room, { limit }) =>
+      Effect.flatMap(
+        Akter.sql,
+        (sql) => sql<Message>`SELECT id, author, text, at FROM messages ORDER BY at DESC LIMIT ${limit}`,
+      ),
+  },
+});
+
+export { RoomLive };

package/src/host/blob/blob-frames.pure.ts

@@ -0,0 +1,52 @@
+import { Stream } from "effect";
+
+interface Framing<Failure, Services> {
+  readonly size: number;
+  readonly source: Stream.Stream<Uint8Array, Failure, Services>;
+}
+
+interface Pending {
+  bytes: Uint8Array;
+  used: number;
+}
+
+const zeroBytes = 0;
+
+const oneFrame = 1;
+
+const pieces = function* pieces(pending: Pending, input: Uint8Array): Generator<Uint8Array> {
+  let offset = zeroBytes;
+
+  while (offset < input.byteLength) {
+    const length = Math.min(pending.bytes.byteLength - pending.used, input.byteLength - offset);
+
+    pending.bytes.set(input.subarray(offset, offset + length), pending.used);
+    pending.used += length;
+    offset += length;
+
+    if (pending.used === pending.bytes.byteLength) {
+      yield pending.bytes;
+
+      pending.bytes = new Uint8Array(pending.bytes.byteLength);
+      pending.used = zeroBytes;
+    }
+  }
+};
+
+const framesOf = <Failure, Services>({
+  size,
+  source,
+}: Framing<Failure, Services>): Stream.Stream<Uint8Array, Failure, Services> =>
+  Stream.suspend(() => {
+    const pending: Pending = { bytes: new Uint8Array(size), used: zeroBytes };
+
+    const complete = Stream.flatMap(source, (bytes) =>
+      Stream.fromIterable(pieces(pending, bytes), { chunkSize: oneFrame }),
+    );
+
+    const final = Stream.suspend(() => Stream.succeed(pending.bytes.subarray(zeroBytes, pending.used)));
+
+    return Stream.concat(complete, final);
+  });
+
+export { framesOf };

package/src/host/blob/blob-grant.schema.ts

@@ -0,0 +1,22 @@
+import { Schema } from "effect";
+
+/**
+ * How a grant's file key is wrapped. `v1` wraps it with the actor key itself, `v2` with a key HKDF-SHA-256 derives
+ * from the actor key, so the one key that encrypts the actor's pages never wraps file keys directly. New grants are v2;
+ * v1 grants written before stay readable.
+ */
+const GrantFormat = Schema.Literals(["xchacha20-poly1305/v1", "xchacha20-poly1305/v2"]);
+
+type GrantFormat = typeof GrantFormat.Type;
+
+const BlobGrant = Schema.Struct({
+  format: GrantFormat,
+  nonce: Schema.Uint8ArrayFromBase64,
+  wrapped: Schema.Uint8ArrayFromBase64,
+});
+
+const BlobGrantJson = Schema.fromJsonString(BlobGrant);
+
+export { BlobGrantJson };
+
+export type { GrantFormat };

package/src/host/blob/blob-grants.service.ts

@@ -0,0 +1,197 @@
+import { Context, Effect, Layer, Redacted, Schema } from "effect";
+import { Aead, Kdf, SecureRandom } from "effect/crypto";
+import type { CryptoError } from "effect/crypto";
+
+import { BlobGrantJson } from "./blob-grant.schema.js";
+import type { GrantFormat } from "./blob-grant.schema.js";
+import { BlobKeyring } from "./blob-keyring.service.js";
+import type { BlobOwnerKey } from "./blob-keyring.service.js";
+import type { Rewrapping } from "./blob-sealing.contract.js";
+import { BlobTransferError } from "#src/contract/file/blob-transfer.errors";
+
+interface Owner {
+  readonly actor: string;
+  readonly blob: string;
+}
+
+interface Opening extends Owner {
+  readonly grant: string;
+}
+
+interface FreshGrant {
+  readonly grant: string;
+  readonly key: Aead.Key;
+}
+
+interface Wrapping extends Owner {
+  readonly key: Aead.Key;
+}
+
+interface GrantKeys {
+  readonly aead: Aead.Aead["Service"];
+  readonly kdf: Kdf.Kdf["Service"];
+  readonly keyring: BlobKeyring["Service"];
+  readonly random: SecureRandom.SecureRandom["Service"];
+}
+
+/** One use of an actor's key: whose, why, and the grant format that says how its wrapping key is made. */
+interface KeyUse extends BlobOwnerKey {
+  readonly format: GrantFormat;
+}
+
+interface BlobGrantsOperations {
+  readonly fresh: (owner: Owner) => Effect.Effect<FreshGrant, BlobTransferError>;
+  readonly open: (opening: Opening) => Effect.Effect<Aead.Key, BlobTransferError>;
+  readonly rewrap: (rewrapping: Rewrapping) => Effect.Effect<string, BlobTransferError>;
+}
+
+const nonceBytes = 24;
+
+const wrappingKeyBytes = 32;
+
+const wiped = 0;
+
+/** The format every grant is written in. */
+const writtenFormat: GrantFormat = "xchacha20-poly1305/v2";
+
+/** The format whose file key is wrapped with the actor key itself, still opened for grants written before v2. */
+const rawKeyFormat: GrantFormat = "xchacha20-poly1305/v1";
+
+/**
+ * HKDF's info for the wrapping key. The salt is empty: the actor key is already a uniformly random 32-byte key, so
+ * RFC 5869 needs no salt for extraction, and the info alone separates this use from the actor's page encryption.
+ */
+const wrappingInfo = new globalThis.TextEncoder().encode("akter/blob-grant/v1");
+
+const noSalt = new Uint8Array();
+
+const crypto = Layer.mergeAll(Aead.layerWebCrypto, Kdf.layerWebCrypto).pipe(
+  Layer.provideMerge(SecureRandom.layerWebCrypto),
+);
+
+const refused = (blob: string): BlobTransferError =>
+  BlobTransferError.make({ blob, message: "the file grant could not be opened for this actor" });
+
+const bindingOf = ({ actor, blob }: Owner): Uint8Array =>
+  new globalThis.TextEncoder().encode(`akter/blob-grant/v1/${actor.length}:${actor}/${blob}`);
+
+/** The bytes of the keyring's key this module owns: the keyring's own buffer if it hands it over, else a copy. */
+const ownedBytes = (keyring: BlobKeyring["Service"], lent: Redacted.Redacted<Uint8Array>): Uint8Array => {
+  const bytes = Redacted.value(lent);
+
+  if (keyring.handsOver === true) {
+    return bytes;
+  }
+
+  return Uint8Array.from(bytes);
+};
+
+const zeroAll = (buffers: readonly Uint8Array[]): void => {
+  for (const bytes of buffers) {
+    bytes.fill(wiped);
+  }
+};
+
+/**
+ * Runs `use` with the wrapping key for one use of an actor's key, and zeroes, in one `ensuring` whatever the outcome,
+ * every buffer of key bytes this module owns for it: the actor key's bytes and the key derived from them.
+ */
+const withWrappingKey = <Value, Failure>(
+  keys: GrantKeys,
+  { format, ...owner }: KeyUse,
+  use: (wrappingKey: Aead.Key) => Effect.Effect<Value, Failure>,
+): Effect.Effect<Value, Failure | BlobTransferError | CryptoError.CryptoError> =>
+  Effect.flatMap(keys.keyring.keyFor(owner), (lent) => {
+    const secret = ownedBytes(keys.keyring, lent);
+    const owned = [secret];
+
+    const keyed = Effect.gen(function* wrappingKeyOf() {
+      if (format === rawKeyFormat) {
+        return yield* Aead.key(Aead.xchacha20Poly1305, secret);
+      }
+
+      const derived = yield* keys.kdf.derive(Kdf.hkdfSha256, secret, {
+        info: wrappingInfo,
+        length: wrappingKeyBytes,
+        salt: noSalt,
+      });
+
+      owned.push(derived);
+
+      return yield* Aead.key(Aead.xchacha20Poly1305, derived);
+    });
+
+    return Effect.flatMap(keyed, use).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          zeroAll(owned);
+        }),
+      ),
+    );
+  });
+
+const wrappingWith = (keys: GrantKeys): ((wrapping: Wrapping) => Effect.Effect<string, BlobTransferError>) =>
+  Effect.fnUntraced(
+    function* wrap({ actor, blob, key }: Wrapping) {
+      const nonce = yield* keys.random.randomBytes(nonceBytes);
+      const use = { actor, blob, format: writtenFormat, intent: "create" } as const;
+
+      const wrapped = yield* withWrappingKey(keys, use, (wrappingKey) =>
+        Effect.flatMap(Aead.toBytes(key), (raw) =>
+          keys.aead
+            .encrypt(wrappingKey, raw, { aad: bindingOf({ actor, blob }), nonce })
+            .pipe(Effect.ensuring(Effect.sync(() => raw.fill(wiped)))),
+        ),
+      );
+
+      return yield* Schema.encodeEffect(BlobGrantJson)({ format: writtenFormat, nonce, wrapped });
+    },
+    (effect, owner) => Effect.mapError(effect, () => refused(owner.blob)),
+  );
+
+const openingWith = (keys: GrantKeys): BlobGrantsOperations["open"] =>
+  Effect.fnUntraced(
+    function* open({ actor, blob, grant }: Opening) {
+      const { format, nonce, wrapped } = yield* Schema.decodeEffect(BlobGrantJson)(grant);
+      const use = { actor, blob, format, intent: "open" } as const;
+
+      return yield* withWrappingKey(keys, use, (wrappingKey) =>
+        Effect.flatMap(keys.aead.decrypt(wrappingKey, wrapped, { aad: bindingOf({ actor, blob }), nonce }), (raw) =>
+          Aead.key(Aead.xchacha20Poly1305, raw).pipe(Effect.ensuring(Effect.sync(() => raw.fill(wiped)))),
+        ),
+      );
+    },
+    (effect, owner) => Effect.mapError(effect, () => refused(owner.blob)),
+  );
+
+export class BlobGrants extends Context.Service<BlobGrants, BlobGrantsOperations>()(
+  "@akterjs/effect/host/blob/blob-grants.service/BlobGrants",
+  {
+    make: Effect.gen(function* makeBlobGrants() {
+      const aead = yield* Aead.Aead;
+      const kdf = yield* Kdf.Kdf;
+      const keyring = yield* BlobKeyring;
+      const random = yield* SecureRandom.SecureRandom;
+      const keys = { aead, kdf, keyring, random };
+      const wrap = wrappingWith(keys);
+      const open = openingWith(keys);
+
+      const fresh = Effect.fnUntraced(function* fresh(owner: Owner) {
+        const key = yield* Effect.mapError(aead.generateKey(Aead.xchacha20Poly1305), () => refused(owner.blob));
+        const grant = yield* wrap({ ...owner, key });
+
+        return { grant, key };
+      });
+
+      const rewrap = Effect.fnUntraced(function* rewrap({ blob, from, grant, to }: Rewrapping) {
+        const key = yield* open({ actor: from, blob, grant });
+
+        return yield* wrap({ actor: to, blob, key });
+      });
+
+      return { fresh, open, rewrap };
+    }),
+  },
+) {
+  public static readonly layer = Layer.effect(this, this.make).pipe(Layer.provide(crypto));
+}

package/src/host/blob/blob-keyring.service.ts

@@ -0,0 +1,25 @@
+import { Context } from "effect";
+import type { Effect, Redacted } from "effect";
+
+import type { BlobTransferError } from "#src/contract/file/blob-transfer.errors";
+
+interface BlobOwnerKey {
+  readonly actor: string;
+  readonly blob: string;
+  readonly intent: "create" | "open";
+}
+
+export class BlobKeyring extends Context.Service<
+  BlobKeyring,
+  {
+    /**
+     * Whether every `keyFor` call returns a buffer of its own that the caller may zero once it is done. When it does,
+     * the grants module zeroes that buffer after each use; otherwise, as for a keyring that caches its keys, it copies
+     * the bytes and zeroes only its copy, so the cached key stays intact for its other users.
+     */
+    readonly handsOver?: boolean;
+    readonly keyFor: (owner: BlobOwnerKey) => Effect.Effect<Redacted.Redacted<Uint8Array>, BlobTransferError>;
+  }
+>()("@akterjs/effect/host/blob/blob-keyring.service/BlobKeyring") {}
+
+export type { BlobOwnerKey };