@samebase/alchemy-convex 0.18.0 → 0.19.1

package/src/store/convex/state.ts

@@ -8,14 +8,65 @@
 // These names and arguments are the wire contract of STORE_VERSION. Samebase
 // reads `stacks`, `getOutput`, and `readStack` by name: a renamed function is
 // a version bump of the store and of Samebase.
+//
+// The rows hold their secrets sealed (see sealing.ts): `set` and `setOutput`
+// are actions that seal and then write, and `get`, `replaced`, and `getOutput`
+// open them for the run. `readStack` gives the rows as they are stored.
+import type { FunctionReturnType } from "convex/server";
 import { v } from "convex/values";
 import { runRecord } from "../component/runRecord.ts";
 import { stackReply } from "../component/state.ts";
-import { components } from "./_generated/api.js";
-import { internalMutation, internalQuery } from "./_generated/server.js";
+import { components, internal } from "./_generated/api.js";
+import {
+  type ActionCtx,
+  internalAction,
+  internalMutation,
+  internalQuery,
+  type MutationCtx,
+} from "./_generated/server.js";
+import {
+  hasSecret,
+  openText,
+  outputAad,
+  requireKey,
+  resealText,
+  resourceAad,
+  sealText,
+} from "./sealing.ts";
 import { STORE_VERSION } from "./version.ts";
 
 const state = components.alchemyState.state;
+const keys = components.alchemyState.keys;
+
+const NO_KEY = "The store has no key yet.";
+
+const currentKey = async (ctx: ActionCtx) => {
+  const { current } = await ctx.runQuery(keys.sealing, {});
+  if (current === null) throw new Error(NO_KEY);
+  return current;
+};
+
+/**
+ * Seals a text and writes it. A write that sealed under a key that stopped being the current key
+ * does not commit, so it cannot land after the reseal of a rotation: it seals again.
+ */
+const sealedWrite = async (
+  ctx: ActionCtx,
+  text: string,
+  aad: string,
+  write: (value: string, keyId: string | null) => Promise<boolean>,
+): Promise<null> => {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const keyId = hasSecret(text) ? await currentKey(ctx) : null;
+    const value = keyId === null ? text : await sealText(text, aad, keyId);
+    if (await write(value, keyId)) return null;
+  }
+  throw new Error("The current key of the store changed during three writes in a row.");
+};
+
+/** True when a value sealed under `keyId` must not commit. A text with no secret has no key. */
+const isStale = async (ctx: MutationCtx, keyId: string | null) =>
+  keyId !== null && (await ctx.runQuery(keys.sealing, {})).current !== keyId;
 
 /** The wire version of this store, compared with the client's STORE_VERSION. */
 export const version = internalQuery({
@@ -47,34 +98,59 @@ export const list = internalQuery({
 export const get = internalQuery({
   args: { stack: v.string(), stage: v.string(), fqn: v.string() },
   returns: v.union(v.string(), v.null()),
-  handler: (ctx, args) =>
-    ctx.runQuery(state.get, { stack: args.stack, stage: args.stage, fqn: args.fqn }),
+  handler: async (ctx, args) => {
+    const row = { stack: args.stack, stage: args.stage, fqn: args.fqn };
+    const value = await ctx.runQuery(state.get, row);
+    return value === null ? null : openText(value, resourceAad(row));
+  },
 });
 
 /** Resources whose state has `status: "replaced"`. */
 export const replaced = internalQuery({
   args: { stack: v.string(), stage: v.string() },
   returns: v.array(v.string()),
-  handler: (ctx, args) => ctx.runQuery(state.replaced, { stack: args.stack, stage: args.stage }),
+  handler: async (ctx, args) => {
+    const rows = await ctx.runQuery(state.replaced, { stack: args.stack, stage: args.stage });
+    return Promise.all(
+      rows.map((row) =>
+        openText(row.value, resourceAad({ stack: args.stack, stage: args.stage, fqn: row.fqn })),
+      ),
+    );
+  },
 });
 
-export const set = internalMutation({
-  args: {
-    stack: v.string(),
-    stage: v.string(),
-    fqn: v.string(),
-    value: v.string(),
-    run: v.optional(runRecord),
-  },
+const setArgs = {
+  stack: v.string(),
+  stage: v.string(),
+  fqn: v.string(),
+  value: v.string(),
+  run: v.optional(runRecord),
+};
+
+export const set = internalAction({
+  args: setArgs,
   returns: v.null(),
-  handler: (ctx, args) =>
-    ctx.runMutation(state.set, {
+  handler: (ctx, args): Promise<null> =>
+    sealedWrite(ctx, args.value, resourceAad(args), (value, keyId) =>
+      ctx.runMutation(internal.state.writeResource, { ...args, value, keyId }),
+    ),
+});
+
+/** The write of `set`. It answers false when `keyId` is no longer the current key. */
+export const writeResource = internalMutation({
+  args: { ...setArgs, keyId: v.union(v.string(), v.null()) },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    if (await isStale(ctx, args.keyId)) return false;
+    await ctx.runMutation(state.set, {
       stack: args.stack,
       stage: args.stage,
       fqn: args.fqn,
       value: args.value,
       run: args.run ?? null,
-    }),
+    });
+    return true;
+  },
 });
 
 export const remove = internalMutation({
@@ -100,19 +176,43 @@ export const removeStack = internalMutation({
 export const getOutput = internalQuery({
   args: { stack: v.string(), stage: v.string() },
   returns: v.union(v.string(), v.null()),
-  handler: (ctx, args) => ctx.runQuery(state.getOutput, { stack: args.stack, stage: args.stage }),
+  handler: async (ctx, args) => {
+    const row = { stack: args.stack, stage: args.stage };
+    const value = await ctx.runQuery(state.getOutput, row);
+    return value === null ? null : openText(value, outputAad(row));
+  },
 });
 
-export const setOutput = internalMutation({
-  args: { stack: v.string(), stage: v.string(), value: v.string(), run: v.optional(runRecord) },
+const setOutputArgs = {
+  stack: v.string(),
+  stage: v.string(),
+  value: v.string(),
+  run: v.optional(runRecord),
+};
+
+export const setOutput = internalAction({
+  args: setOutputArgs,
   returns: v.null(),
-  handler: (ctx, args) =>
-    ctx.runMutation(state.setOutput, {
+  handler: (ctx, args): Promise<null> =>
+    sealedWrite(ctx, args.value, outputAad(args), (value, keyId) =>
+      ctx.runMutation(internal.state.writeOutput, { ...args, value, keyId }),
+    ),
+});
+
+/** The write of `setOutput`. It answers false when `keyId` is no longer the current key. */
+export const writeOutput = internalMutation({
+  args: { ...setOutputArgs, keyId: v.union(v.string(), v.null()) },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    if (await isStale(ctx, args.keyId)) return false;
+    await ctx.runMutation(state.setOutput, {
       stack: args.stack,
       stage: args.stage,
       value: args.value,
       run: args.run ?? null,
-    }),
+    });
+    return true;
+  },
 });
 
 /** Every stage of a stack with its resources, output, and current record, in one call. Since store version 2. */
@@ -121,3 +221,129 @@ export const readStack = internalQuery({
   returns: stackReply,
   handler: (ctx, args) => ctx.runQuery(state.readStack, { stack: args.stack }),
 });
+
+/** The current key, and true when every secret is sealed under it. A run reads this each time. */
+export const sealing = internalQuery({
+  args: {},
+  returns: v.object({
+    current: v.union(v.string(), v.null()),
+    generation: v.number(),
+    sealed: v.boolean(),
+  }),
+  handler: (ctx) => ctx.runQuery(keys.sealing, {}),
+});
+
+/**
+ * Makes `keyId` the current key of a store with no key, and answers the current key. Two first runs
+ * can both call it: the first one wins, and the variable of the other stays unused.
+ */
+export const chooseKey = internalMutation({
+  args: { keyId: v.string() },
+  returns: v.string(),
+  handler: (ctx, args) => {
+    requireKey(args.keyId);
+    return ctx.runMutation(keys.choose, args);
+  },
+});
+
+/** Makes `keyId`, a key that the deployment holds, the current key. See `reseal`. */
+export const rotateKey = internalMutation({
+  args: { keyId: v.string() },
+  returns: v.null(),
+  handler: (ctx, args) => {
+    requireKey(args.keyId);
+    return ctx.runMutation(keys.rotate, args);
+  },
+});
+
+/**
+ * Seals every secret of the store under the current key, one row at a time, through bounded pages.
+ * A run calls it until one finishes, so a run that stops only leaves work for the next one, and the
+ * rows that it sealed stay sealed. A row that fails, because a key is gone or a write limit was hit,
+ * is named in `failed`, and the others go on. A row that changed during the sweep is left: the write
+ * that changed it sealed it. A sweep
+ * stops when the current key changes: the sweep of the new key does the work, and this one must not
+ * put the older key back.
+ */
+export const reseal = internalAction({
+  args: {},
+  returns: v.object({
+    resealed: v.number(),
+    skippedChanged: v.number(),
+    failed: v.array(v.string()),
+  }),
+  handler: async (ctx) => {
+    const { current: keyId, generation } = await ctx.runQuery(keys.sealing, {});
+    if (keyId === null) throw new Error(NO_KEY);
+    let resealed = 0;
+    let skippedChanged = 0;
+    const failed: string[] = [];
+    /** Reseals one row, and answers true when the sweep must stop. */
+    const sweep = async (
+      name: string,
+      aad: string,
+      expected: string,
+      replace: (value: string) => Promise<"replaced" | "changed" | "stale">,
+    ) => {
+      try {
+        const value = await resealText(expected, aad, keyId);
+        if (value === expected) return false;
+        const result = await replace(value);
+        if (result === "replaced") resealed += 1;
+        if (result === "changed") skippedChanged += 1;
+        return result === "stale";
+      } catch {
+        // The row name is enough: an error can name a key id, and it adds nothing to find the row.
+        failed.push(name);
+        return false;
+      }
+    };
+    const done = () => ({ resealed, skippedChanged, failed });
+
+    let cursor: string | null = null;
+    for (;;) {
+      const { page, continueCursor, isDone }: FunctionReturnType<typeof state.resourcePage> =
+        await ctx.runQuery(state.resourcePage, { cursor });
+      for (const { stack, stage, fqn, value: expected } of page) {
+        const stale = await sweep(
+          `${stack}/${stage}/${fqn}`,
+          resourceAad({ stack, stage, fqn }),
+          expected,
+          (value) =>
+            ctx.runMutation(state.replaceResource, {
+              stack,
+              stage,
+              fqn,
+              expected,
+              value,
+              generation,
+            }),
+        );
+        if (stale) return done();
+      }
+      if (isDone) break;
+      cursor = continueCursor;
+    }
+
+    cursor = null;
+    for (;;) {
+      const { page, continueCursor, isDone }: FunctionReturnType<typeof state.outputPage> =
+        await ctx.runQuery(state.outputPage, { cursor });
+      for (const { stack, stage, value: expected } of page) {
+        const stale = await sweep(
+          `${stack}/${stage} output`,
+          outputAad({ stack, stage }),
+          expected,
+          (value) =>
+            ctx.runMutation(state.replaceOutput, { stack, stage, expected, value, generation }),
+        );
+        if (stale) return done();
+      }
+      if (isDone) break;
+      cursor = continueCursor;
+    }
+
+    if (failed.length === 0) await ctx.runMutation(keys.markSealed, { generation });
+    return done();
+  },
+});

package/src/store/convex/version.ts

@@ -10,4 +10,6 @@
 // 2: `readStack` (0.7.0).
 // 3: authenticated subscriptions and current stage run records (0.9.0).
 // 4: the store is a component (same functions).
-export const STORE_VERSION = 4;
+// 5: rows hold their secrets sealed: `set` and `setOutput` are actions, with `sealing`, `chooseKey`,
+//    `rotateKey`, and `reseal` (0.19.0).
+export const STORE_VERSION = 5;

package/src/store/sealedSecret.ts

@@ -0,0 +1,129 @@
+// AES-256-GCM sealing under a key ring, with Web Crypto only, so that it runs in Convex and in Node.
+//
+// A key ring is the JSON text `{"current":"<keyId>","keys":{"<keyId>":"<base64 of 32 bytes>"}}`,
+// which a deployment keeps in one environment variable. `sealSecret` seals with the `current` key.
+// `openSecret` opens with the key that the sealed object names, so an old key stays in the ring
+// until a reseal moves its values to the current key.
+//
+// Seal only where randomness is real: in a Convex action, or outside Convex. In a Convex query or
+// mutation `crypto.getRandomValues` is a seeded deterministic generator, and a repeated IV under one
+// key breaks AES-GCM. Opening draws no randomness, so a query can open.
+
+/** A value sealed with AES-256-GCM under the key `keyId` of a key ring. */
+export interface SealedSecret {
+  readonly keyId: string;
+  /** 12 random bytes, base64url. */
+  readonly iv: string;
+  /** The AES-GCM output with its 16-byte tag, base64url. */
+  readonly ciphertext: string;
+}
+
+export interface KeyRing {
+  readonly current: string;
+  readonly keys: ReadonlyMap<string, Uint8Array<ArrayBuffer>>;
+}
+
+const toBase64 = (bytes: Uint8Array) =>
+  btoa(Array.from(bytes, (byte) => String.fromCharCode(byte)).join(""));
+
+const toBase64Url = (bytes: Uint8Array) =>
+  toBase64(bytes).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+
+/** The bytes of base64 or base64url text. */
+const fromBase64 = (text: string) => {
+  const standard = text.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = standard.padEnd(standard.length + ((4 - (standard.length % 4)) % 4), "=");
+  return Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+};
+
+/** A key of 32 bytes in base64 is 43 characters and one `=`. */
+const KEY_TEXT = /^[A-Za-z0-9+/]{43}=$/;
+
+/**
+ * The key ring in the text of the variable `name`. It fails closed when the text is missing or
+ * malformed, or when the current key id has no key. An error never quotes the text, which holds
+ * the keys.
+ */
+export const parseKeyRing = (name: string, text: string | undefined): KeyRing => {
+  let value: unknown;
+  try {
+    value = JSON.parse(text ?? "");
+  } catch {
+    throw new Error(`${name} is missing or is not JSON.`);
+  }
+  const malformed = new Error(
+    `${name} must be {"current":"<keyId>","keys":{"<keyId>":"<base64 of 32 bytes>"}}.`,
+  );
+  if (typeof value !== "object" || value === null) throw malformed;
+  if (!("current" in value) || !("keys" in value)) throw malformed;
+  const { current, keys: keyTexts } = value;
+  if (typeof current !== "string" || typeof keyTexts !== "object" || keyTexts === null) {
+    throw malformed;
+  }
+  const keys = new Map<string, Uint8Array<ArrayBuffer>>();
+  for (const [keyId, key] of Object.entries(keyTexts)) {
+    if (typeof key !== "string" || !KEY_TEXT.test(key)) throw malformed;
+    keys.set(keyId, fromBase64(key));
+  }
+  if (!keys.has(current)) throw new Error(`${name} has no key for its current key id.`);
+  return { current, keys };
+};
+
+/** A random key id of 12 hexadecimal characters, which is also safe in a variable name. */
+export const newKeyId = (): string =>
+  Array.from(crypto.getRandomValues(new Uint8Array(6)), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+
+/** A random key of 32 bytes in base64. It needs real randomness, like `sealSecret`. */
+export const newKey = (): string => toBase64(crypto.getRandomValues(new Uint8Array(32)));
+
+/** The text of a new key ring with one random key. */
+export const newKeyRing = (): string => {
+  const keyId = newKeyId();
+  return JSON.stringify({ current: keyId, keys: { [keyId]: newKey() } });
+};
+
+const importKey = (ring: KeyRing, keyId: string) => {
+  const bytes = ring.keys.get(keyId);
+  if (bytes === undefined) throw new Error(`The key ring has no key "${keyId}".`);
+  return crypto.subtle.importKey("raw", bytes, "AES-GCM", false, ["encrypt", "decrypt"]);
+};
+
+/** Seals `plaintext` with the current key. `aad` names the owner, so the value opens only there. */
+export const sealSecret = async (
+  ring: KeyRing,
+  args: { readonly plaintext: string; readonly aad: string },
+): Promise<SealedSecret> => {
+  const key = await importKey(ring, ring.current);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: new TextEncoder().encode(args.aad) },
+    key,
+    new TextEncoder().encode(args.plaintext),
+  );
+  return {
+    keyId: ring.current,
+    iv: toBase64Url(iv),
+    ciphertext: toBase64Url(new Uint8Array(ciphertext)),
+  };
+};
+
+/** Opens a sealed value with the key it names. A different `aad` or a changed value fails. */
+export const openSecret = async (
+  ring: KeyRing,
+  args: { readonly sealed: SealedSecret; readonly aad: string },
+): Promise<string> => {
+  const { sealed } = args;
+  const key = await importKey(ring, sealed.keyId);
+  const plaintext = await crypto.subtle.decrypt(
+    {
+      name: "AES-GCM",
+      iv: fromBase64(sealed.iv),
+      additionalData: new TextEncoder().encode(args.aad),
+    },
+    key,
+    fromBase64(sealed.ciphertext),
+  );
+  return new TextDecoder().decode(plaintext);
+};