@samebase/alchemy-convex 0.18.0 → 0.19.1

package/src/store/component/_generated/component.ts

@@ -23,6 +23,36 @@ import type { FunctionReference } from "convex/server";
  */
 export type ComponentApi<Name extends string | undefined = string | undefined> =
   {
+    keys: {
+      choose: FunctionReference<
+        "mutation",
+        "internal",
+        { keyId: string },
+        string,
+        Name
+      >;
+      markSealed: FunctionReference<
+        "mutation",
+        "internal",
+        { generation: number },
+        null,
+        Name
+      >;
+      rotate: FunctionReference<
+        "mutation",
+        "internal",
+        { keyId: string },
+        null,
+        Name
+      >;
+      sealing: FunctionReference<
+        "query",
+        "internal",
+        {},
+        { current: string | null; generation: number; sealed: boolean },
+        Name
+      >;
+    };
     reader: {
       repository: FunctionReference<
         "query",
@@ -76,6 +106,17 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Array<string>,
         Name
       >;
+      outputPage: FunctionReference<
+        "query",
+        "internal",
+        { cursor: string | null },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<{ stack: string; stage: string; value: string }>;
+        },
+        Name
+      >;
       readStack: FunctionReference<
         "query",
         "internal",
@@ -133,7 +174,50 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "query",
         "internal",
         { stack: string; stage: string },
-        Array<string>,
+        Array<{ fqn: string; value: string }>,
+        Name
+      >;
+      replaceOutput: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          expected: string;
+          generation: number;
+          stack: string;
+          stage: string;
+          value: string;
+        },
+        "replaced" | "changed" | "stale",
+        Name
+      >;
+      replaceResource: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          expected: string;
+          fqn: string;
+          generation: number;
+          stack: string;
+          stage: string;
+          value: string;
+        },
+        "replaced" | "changed" | "stale",
+        Name
+      >;
+      resourcePage: FunctionReference<
+        "query",
+        "internal",
+        { cursor: string | null },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<{
+            fqn: string;
+            stack: string;
+            stage: string;
+            value: string;
+          }>;
+        },
         Name
       >;
       set: FunctionReference<

package/src/store/component/keys.ts

@@ -0,0 +1,73 @@
+// The keys of the store: one row that names the current key, and the key under which every secret
+// is sealed. The keys themselves are variables of the deployment, and a component cannot read them.
+import { v } from "convex/values";
+import type { QueryCtx } from "./_generated/server.js";
+// oxlint-disable-next-line samebase/no-raw-public-convex-function-builders -- Store entrypoints have no app wrapper; the deploy key enforces access.
+import { mutation, query } from "./_generated/server.js";
+
+const rowOf = (ctx: QueryCtx) => ctx.db.query("keys").first();
+
+/** The generation of the current key, read in the transaction of the caller. */
+export const generationOf = async (ctx: QueryCtx) => (await rowOf(ctx))?.generation ?? null;
+
+/**
+ * The current key, its generation, and true when a reseal of that generation finished. Each
+ * rotation is a new generation, also when a key comes back, so a sweep that a rotation overtook can
+ * never pass for the current one.
+ */
+export const sealing = query({
+  args: {},
+  returns: v.object({
+    current: v.union(v.string(), v.null()),
+    generation: v.number(),
+    sealed: v.boolean(),
+  }),
+  handler: async (ctx) => {
+    const row = await rowOf(ctx);
+    if (row === null) return { current: null, generation: 0, sealed: false };
+    const { current, generation, sealedGeneration } = row;
+    return { current, generation, sealed: sealedGeneration === generation };
+  },
+});
+
+/** Makes `keyId` the current key of a store with no key, and answers the current key. */
+export const choose = mutation({
+  args: { keyId: v.string() },
+  returns: v.string(),
+  handler: async (ctx, args) => {
+    const row = await rowOf(ctx);
+    if (row !== null) return row.current;
+    await ctx.db.insert("keys", { current: args.keyId, generation: 1 });
+    return args.keyId;
+  },
+});
+
+/** Makes `keyId` the current key, in a new generation. The next reseal moves the secrets to it. */
+export const rotate = mutation({
+  args: { keyId: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const row = await rowOf(ctx);
+    if (row === null) await ctx.db.insert("keys", { current: args.keyId, generation: 1 });
+    else {
+      await ctx.db.patch("keys", row._id, {
+        current: args.keyId,
+        generation: row.generation + 1,
+      });
+    }
+    return null;
+  },
+});
+
+/** Records a finished reseal. It does nothing when a rotation came after the sweep started. */
+export const markSealed = mutation({
+  args: { generation: v.number() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const row = await rowOf(ctx);
+    if (row?.generation === args.generation) {
+      await ctx.db.patch("keys", row._id, { sealedGeneration: args.generation });
+    }
+    return null;
+  },
+});

package/src/store/component/reader.ts

@@ -2,6 +2,7 @@
 // token and passes the repository that the token names: a component has no
 // `ctx.auth`.
 import { v, type Infer } from "convex/values";
+// oxlint-disable-next-line samebase/no-raw-public-convex-function-builders -- Store entrypoints have no app wrapper; the reader and the deploy key enforce access.
 import { query } from "./_generated/server.js";
 import { runRecord, validate } from "./runRecord.ts";
 

package/src/store/component/runRecord.ts

@@ -16,6 +16,7 @@ export const runRecord = v.object({
 export const validate = <V extends GenericValidator>(
   validator: V,
   value: unknown,
+  // eslint-disable-next-line samebase/no-hand-written-type-predicate -- A component imports no app package, and the switch walks the validator itself.
 ): value is Infer<V> => {
   switch (validator.kind) {
     case "object": {

package/src/store/component/schema.ts

@@ -18,4 +18,11 @@ export default defineSchema({
     value: v.optional(v.string()),
     currentRun: v.optional(runRecord),
   }).index("by_stage", ["stack", "stage"]),
+  // One row: the key that seals new secrets, the count of its rotations, and the last count for
+  // which a reseal finished.
+  keys: defineTable({
+    current: v.string(),
+    generation: v.number(),
+    sealedGeneration: v.optional(v.number()),
+  }),
 });

package/src/store/component/state.ts

@@ -5,9 +5,11 @@
 //
 // A stage holds one row for each resource of its stack, so the reads of one
 // stage collect all rows.
-import { v, type Infer } from "convex/values";
+import { v, type Infer, type Validator } from "convex/values";
 import type { MutationCtx, QueryCtx } from "./_generated/server.js";
+// oxlint-disable-next-line samebase/no-raw-public-convex-function-builders -- Store entrypoints have no app wrapper; the reader and the deploy key enforce access.
 import { mutation, query } from "./_generated/server.js";
+import { generationOf } from "./keys.ts";
 import { runRecord } from "./runRecord.ts";
 
 const stage = { stack: v.string(), stage: v.string() };
@@ -147,11 +149,11 @@ export const get = query({
 /** Resources whose state has `status: "replaced"`. */
 export const replaced = query({
   args: stage,
-  returns: v.array(v.string()),
+  returns: v.array(v.object({ fqn: v.string(), value: v.string() })),
   handler: async (ctx, args) =>
     (await rowsOf(ctx, args))
-      .map((row) => row.value)
-      .filter((value) => {
+      .map((row) => ({ fqn: row.fqn, value: row.value }))
+      .filter(({ value }) => {
         const parsed: unknown = JSON.parse(value);
         return (
           typeof parsed === "object" &&
@@ -234,6 +236,86 @@ export const setOutput = mutation({
   },
 });
 
+/** A document holds at most 1 MiB, so one page reads less than the 16 MiB of one function. */
+const RESEAL_PAGE = 10;
+
+const pageOf = <Row extends Validator<unknown, "required", string>>(row: Row) =>
+  v.object({ page: v.array(row), continueCursor: v.string(), isDone: v.boolean() });
+
+const resealRow = v.object({ ...resource, value: v.string() });
+
+/**
+ * One bounded page of the resources, in table order, for a reseal. `list` and `readStack` read a
+ * whole stage or stack, which can pass the read limit of one function.
+ */
+export const resourcePage = query({
+  args: { cursor: v.union(v.string(), v.null()) },
+  returns: pageOf(resealRow),
+  handler: async (ctx, args) => {
+    const { page, continueCursor, isDone } = await ctx.db
+      .query("resources")
+      .paginate({ cursor: args.cursor, numItems: RESEAL_PAGE });
+    return {
+      page: page.map(({ stack, stage, fqn, value }) => ({ stack, stage, fqn, value })),
+      continueCursor,
+      isDone,
+    };
+  },
+});
+
+/** One bounded page of the outputs. A row with only a run record has no value and is left out. */
+export const outputPage = query({
+  args: { cursor: v.union(v.string(), v.null()) },
+  returns: pageOf(v.object({ ...stage, value: v.string() })),
+  handler: async (ctx, args) => {
+    const { page, continueCursor, isDone } = await ctx.db
+      .query("outputs")
+      .paginate({ cursor: args.cursor, numItems: RESEAL_PAGE });
+    return {
+      page: page.flatMap(({ stack, stage, value }) =>
+        value === undefined ? [] : [{ stack, stage, value }],
+      ),
+      continueCursor,
+      isDone,
+    };
+  },
+});
+
+/**
+ * What a reseal write did. `stale` means that a rotation came after the sweep started: that sweep
+ * must not put an older key back over the work of a newer one.
+ */
+const replaceResult = v.union(v.literal("replaced"), v.literal("changed"), v.literal("stale"));
+
+/**
+ * Replaces the value of a row that still holds `expected`, for a reseal of `generation`: the row
+ * keeps its run record.
+ */
+export const replaceResource = mutation({
+  args: { ...resource, expected: v.string(), value: v.string(), generation: v.number() },
+  returns: replaceResult,
+  handler: async (ctx, args) => {
+    if ((await generationOf(ctx)) !== args.generation) return "stale";
+    const row = await rowOf(ctx, args);
+    if (row === null || row.value !== args.expected) return "changed";
+    await ctx.db.patch("resources", row._id, { value: args.value });
+    return "replaced";
+  },
+});
+
+/** Like {@link replaceResource}, for an output. */
+export const replaceOutput = mutation({
+  args: { ...stage, expected: v.string(), value: v.string(), generation: v.number() },
+  returns: replaceResult,
+  handler: async (ctx, args) => {
+    if ((await generationOf(ctx)) !== args.generation) return "stale";
+    const row = await outputOf(ctx, args);
+    if (row === null || row.value !== args.expected) return "changed";
+    await ctx.db.patch("outputs", row._id, { value: args.value });
+    return "replaced";
+  },
+});
+
 /** The reply of {@link readStack}. */
 export const stackReply = v.object({
   stages: v.array(

package/src/store/convex/_generated/api.d.ts

@@ -9,6 +9,7 @@
  */
 
 import type * as reader from "../reader.js";
+import type * as sealing from "../sealing.js";
 import type * as state from "../state.js";
 import type * as version from "../version.js";
 
@@ -20,6 +21,7 @@ import type {
 
 declare const fullApi: ApiFromModules<{
   reader: typeof reader;
+  sealing: typeof sealing;
   state: typeof state;
   version: typeof version;
 }>;

package/src/store/convex/reader.ts

@@ -4,6 +4,7 @@
 import { v } from "convex/values";
 import { repositoryReply } from "../component/reader.ts";
 import { components } from "./_generated/api.js";
+// oxlint-disable-next-line samebase/no-raw-public-convex-function-builders -- Store entrypoints have no app wrapper; the reader and the deploy key enforce access.
 import { env, internalMutation, query } from "./_generated/server.js";
 
 const repositoryName = /^[^/]+\/[^/]+$/;

package/src/store/convex/sealing.ts

@@ -0,0 +1,102 @@
+// The secrets of the state rows. Alchemy's `encodeState` writes a `Redacted` value in clear text as
+// `{ "__redacted__": <value> }`. A row holds `{ "__redacted__": { "__sealed__": <sealed> } }`, so a
+// table view, a snapshot, or a reader that forgets to remove secrets shows no value.
+//
+// Each key is one variable `STATE_KEY_<keyId>` of the store deployment, and a sealed value names its
+// key. So two runs that make a key at the same time add two variables, and neither can replace a
+// key that a row needs. The table `keys` of the component names the current key: that choice is a
+// transaction, so the first run wins, and a write that sealed under an older key cannot commit.
+//
+// `state:set` and `state:setOutput` seal in an action, and the reads of a run open in a query.
+// `state:readStack` and `reader:repository` give the rows as they are stored, without their
+// secrets. A value without `__sealed__` is one that `state:reseal` has not reached yet.
+import { openSecret, parseKeyRing, sealSecret, type SealedSecret } from "../sealedSecret.ts";
+
+const REDACTED = "__redacted__";
+const SEALED = "__sealed__";
+
+/** The variable of the store deployment that holds the key `keyId`. */
+export const stateKeyName = (keyId: string) => `STATE_KEY_${keyId}`;
+
+/** The one key `keyId` as a key ring. It fails when the variable is missing or malformed. */
+const keyRingOf = (keyId: string) => {
+  const name = stateKeyName(keyId);
+  return parseKeyRing(
+    name,
+    JSON.stringify({ current: keyId, keys: { [keyId]: process.env[name] } }),
+  );
+};
+
+/** Fails unless the deployment holds the key `keyId`, before a function makes it the current key. */
+export const requireKey = (keyId: string) => {
+  keyRingOf(keyId);
+};
+
+// eslint-disable-next-line samebase/no-hand-written-type-predicate -- The store imports no app package, and this check is exactly the JSON object that the predicate names.
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** The sealed object of a `__redacted__` value, or undefined for a value in clear text. */
+const sealedIn = (value: unknown): SealedSecret | undefined => {
+  if (!isRecord(value) || !isRecord(value[SEALED])) return undefined;
+  const { keyId, iv, ciphertext } = value[SEALED];
+  return typeof keyId === "string" && typeof iv === "string" && typeof ciphertext === "string"
+    ? { keyId, iv, ciphertext }
+    : undefined;
+};
+
+/** `value` with each `__redacted__` value replaced by the result of `change`. */
+const mapSecrets = async (
+  value: unknown,
+  change: (secret: unknown) => Promise<unknown>,
+): Promise<unknown> => {
+  if (Array.isArray(value)) return Promise.all(value.map((item) => mapSecrets(item, change)));
+  if (!isRecord(value)) return value;
+  if (REDACTED in value) return { [REDACTED]: await change(value[REDACTED]) };
+  const entries = await Promise.all(
+    Object.entries(value).map(async ([key, item]) => [key, await mapSecrets(item, change)]),
+  );
+  return Object.fromEntries(entries);
+};
+
+/** True when a JSON text of `encodeState` can hold a secret. */
+export const hasSecret = (text: string) => text.includes(REDACTED);
+
+/** The JSON text with each secret changed. A text without a secret stays the same text. */
+const mapText = async (text: string, change: (secret: unknown) => Promise<unknown>) =>
+  hasSecret(text) ? JSON.stringify(await mapSecrets(JSON.parse(text), change)) : text;
+
+const sealValue = async (value: unknown, aad: string, keyId: string) => ({
+  [SEALED]: await sealSecret(keyRingOf(keyId), { plaintext: JSON.stringify(value), aad }),
+});
+
+const openValue = async (sealed: SealedSecret, aad: string): Promise<unknown> =>
+  JSON.parse(await openSecret(keyRingOf(sealed.keyId), { sealed, aad }));
+
+/** The owner of a resource row: a sealed value opens only in the row that sealed it. */
+export const resourceAad = (row: { stack: string; stage: string; fqn: string }) =>
+  JSON.stringify(["resource", row.stack, row.stage, row.fqn]);
+
+/** The owner of an output row. */
+export const outputAad = (row: { stack: string; stage: string }) =>
+  JSON.stringify(["output", row.stack, row.stage]);
+
+/** Seals each secret of a JSON text of `encodeState`. Only an action can call it. */
+export const sealText = (text: string, aad: string, keyId: string) =>
+  mapText(text, (secret) => sealValue(secret, aad, keyId));
+
+/** Opens each secret of a row, for the reads of a run. */
+export const openText = (text: string, aad: string) =>
+  mapText(text, async (secret) => {
+    const sealed = sealedIn(secret);
+    return sealed === undefined ? secret : openValue(sealed, aad);
+  });
+
+/** The row with every secret sealed under `keyId`. Only an action can call it. */
+export const resealText = (text: string, aad: string, keyId: string) =>
+  mapText(text, async (secret) => {
+    const sealed = sealedIn(secret);
+    if (sealed === undefined) return sealValue(secret, aad, keyId);
+    if (sealed.keyId === keyId) return secret;
+    return sealValue(await openValue(sealed, aad), aad, keyId);
+  });