@samebase/alchemy-convex 0.14.1 → 0.16.0

package/src/HubClient.ts

@@ -0,0 +1,260 @@
+// Convex.HubClient: one deployment of an app as a client of the identity hub
+// of its team.
+//
+// The hub is the production deployment of the project `samebase` of the team.
+// It has the internal functions of `@samebase/identity-broker` in its module
+// `identityBroker`. This resource finds the project by name and runs those
+// functions with a short-lived key, so a stack that has the Convex credential
+// of the team needs no other credential and no hub address. The hub answers
+// with its issuer and the client.
+//
+// The hub keeps only the hash of the secret, so the state is the only record
+// of it. A client belongs to one redirect URI: another URI is a new client. A
+// change of `app` updates the stored props and does not move the client: the
+// app is the identity of the users of the app, and it does not change. The
+// team does not change either: the state of a stack is in its team.
+import { Resource } from "alchemy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { ManagementApi, type ManagementApiService } from "./ManagementApi.ts";
+import { findProjectByName, prodDeploymentOf } from "./Project.ts";
+import type { Providers } from "./Providers.ts";
+import { withPushKey } from "./Push.ts";
+import { type FunctionApi, makeFunctionApi, RUN_KEY_ACTIONS } from "./State.ts";
+
+/** The name of the project of the hub in each team. */
+export const HUB_PROJECT_NAME = "samebase";
+
+export type HubDeploymentType = "production" | "development" | "preview";
+
+export interface HubClientProps {
+  /** The Convex team, a slug or an id, whose project `samebase` holds the hub. */
+  readonly team: string | number;
+  /** The app on the hub, such as `scout`. The first client of an app creates it, as a first-party app. */
+  readonly app: string;
+  /** The deployment's callback URL, such as `<deployment site URL>/auth/hub/callback`. */
+  readonly redirectUri: string;
+  readonly deploymentType: HubDeploymentType;
+  /** The name the hub records for the client. */
+  readonly clientName: string;
+  /** Recorded on the hub's client, such as the commit. The hub records "unknown" without it. */
+  readonly softwareVersion?: string;
+}
+
+export interface HubClientAttributes {
+  /** The issuer of the hub, which the deployment names to sign in. */
+  readonly issuer: string;
+  readonly redirectUri: string;
+  readonly deploymentType: HubDeploymentType;
+  /** The name the client was registered with. */
+  readonly clientName: string;
+  readonly clientId: string;
+  /** Returned by the hub only at registration. */
+  readonly clientSecret: Redacted.Redacted<string>;
+}
+
+export type HubClient = Resource<
+  "IdentityHub.Client",
+  HubClientProps,
+  HubClientAttributes,
+  never,
+  Providers
+>;
+export const HubClient = Resource<HubClient>("IdentityHub.Client");
+
+/** The hub of the team could not do the call. The reason is the Convex message: it holds no secret. */
+export class HubClientFailed extends Schema.TaggedError<HubClientFailed>()("HubClientFailed", {
+  team: Schema.Union([Schema.String, Schema.Number]),
+  reason: Schema.String,
+}) {
+  override get message() {
+    return `Convex.HubClient: the hub of team ${this.team}: ${this.reason}.`;
+  }
+}
+
+/** The reply of `identityBroker:registerClient`. */
+const Registered = Schema.Struct({
+  issuer: Schema.NonEmptyString,
+  clientId: Schema.NonEmptyString,
+  clientSecret: Schema.NonEmptyString,
+});
+
+/** Runs `use` with the function API of the hub of `team`, with a key of this call only. */
+const withHub = <A, E, R>(
+  api: ManagementApiService,
+  team: string | number,
+  use: (functions: FunctionApi) => Effect.Effect<A, E, R>,
+) =>
+  Effect.gen(function* () {
+    const teamId = yield* api.resolveTeamId(team);
+    const project = yield* findProjectByName(api, teamId, HUB_PROJECT_NAME);
+    if (project === undefined) {
+      return yield* new HubClientFailed({
+        team,
+        reason: `no project ${HUB_PROJECT_NAME}, which holds the hub`,
+      });
+    }
+    const deployment = yield* prodDeploymentOf(api, project.id);
+    if (deployment === undefined) {
+      return yield* new HubClientFailed({
+        team,
+        reason: `project ${HUB_PROJECT_NAME} has no production deployment`,
+      });
+    }
+    return yield* withPushKey(api, deployment.name, RUN_KEY_ACTIONS, (key) =>
+      use(makeFunctionApi(deployment.deploymentUrl, key)),
+    );
+  });
+
+/** One internal function of the hub: its value, or the Convex message as an error. */
+const runHub = (
+  functions: FunctionApi,
+  team: string | number,
+  name: string,
+  args: Record<string, string>,
+) =>
+  functions.call(`identityBroker:${name}`, args).pipe(
+    Effect.mapError((error) => new HubClientFailed({ team, reason: error.message })),
+    Effect.flatMap((reply) =>
+      reply.status === "success"
+        ? Effect.succeed(reply.value)
+        : Effect.fail(new HubClientFailed({ team, reason: reply.errorMessage.trim() })),
+    ),
+  );
+
+/**
+ * Registers one client. An attempt that a lost reply repeats leaves one spare
+ * client on the hub, which signs nobody in.
+ */
+export const registerHubClient = (api: ManagementApiService, props: HubClientProps) =>
+  withHub(api, props.team, (functions) =>
+    runHub(functions, props.team, "registerClient", {
+      appId: props.app,
+      redirectUri: props.redirectUri,
+      deploymentType: props.deploymentType,
+      clientName: props.clientName,
+      softwareVersion: props.softwareVersion ?? "unknown",
+      // Convex Auth's generic OAuth method posts the client credentials in the body.
+      tokenEndpointAuthMethod: "client_secret_post",
+    }),
+  ).pipe(
+    Effect.flatMap((value) =>
+      Schema.decodeUnknownEffect(Registered)(value).pipe(
+        Effect.mapError(
+          () => new HubClientFailed({ team: props.team, reason: "registerClient gave no client" }),
+        ),
+      ),
+    ),
+    Effect.map(({ issuer, clientId, clientSecret }) => ({
+      issuer,
+      clientId,
+      clientSecret: Redacted.make(clientSecret),
+    })),
+  );
+
+const unregister = (api: ManagementApiService, team: string | number, clientId: string) =>
+  withHub(api, team, (functions) => runHub(functions, team, "deleteClient", { clientId }));
+
+/** True when the client in state serves the redirect URI and deployment type of `props`. */
+const registeredFor = (output: HubClientAttributes, props: HubClientProps) =>
+  output.redirectUri === props.redirectUri && output.deploymentType === props.deploymentType;
+
+export const HubClientProvider = () =>
+  Provider.effect(
+    HubClient,
+    Effect.gen(function* () {
+      const api = yield* ManagementApi;
+      return {
+        diff: ({ news, olds, output }) =>
+          Effect.succeed(
+            // Props that are unresolved at plan time, such as a redirectUri from a deployment that
+            // this run creates, are compared in reconcile.
+            !isResolved(news) || output === undefined
+              ? undefined
+              : !registeredFor(output, news)
+                ? ({ action: "replace" } as const)
+                : olds.team === news.team && olds.app === news.app
+                  ? ({ action: "noop" } as const)
+                  : ({ action: "update" } as const),
+          ),
+
+        read: ({ output }) => Effect.succeed(output),
+
+        reconcile: Effect.fn(function* ({ news, output }) {
+          if (output !== undefined && registeredFor(output, news)) return output;
+          const client = yield* registerHubClient(api, news);
+          // An update whose props were unresolved at plan time registers in place of a
+          // replacement. The new client is returned whatever happens to the old one.
+          if (output !== undefined) {
+            yield* unregister(api, news.team, output.clientId).pipe(
+              Effect.catchTag("HubClientFailed", (error) =>
+                Effect.logWarning(
+                  `Client ${output.clientId} stays on the hub: ${error.message} Delete it with \`npx convex run --prod identityBroker:deleteClient\`.`,
+                ),
+              ),
+            );
+          }
+          return {
+            ...client,
+            redirectUri: news.redirectUri,
+            deploymentType: news.deploymentType,
+            clientName: news.clientName,
+          };
+        }),
+
+        delete: ({ olds, output }) =>
+          unregister(api, olds.team, output.clientId).pipe(Effect.asVoid),
+      };
+    }),
+  );
+
+export interface DevelopmentClientOptions {
+  readonly team: string | number;
+  readonly app: string;
+  /** The path of the hub's callback after the site URL of the deployment. */
+  readonly callbackPath: string;
+  /** Runs the Convex CLI on the deployment of this directory, and answers its output. */
+  readonly convex: (args: readonly string[], input?: string) => string;
+}
+
+/** The variables that a deployment reads to sign in through the hub. */
+const HUB_VARIABLES = ["HUB_ISSUER", "HUB_CLIENT_ID", "HUB_CLIENT_SECRET"];
+
+/**
+ * `alchemy-convex hub-client`: a stack deploys production and previews, and this covers the
+ * development deployment, which no stack deploys. A deployment with all three variables keeps
+ * them. So a deployment that holds placeholder values for a checkout without a hub is left alone.
+ * The secret reaches the Convex CLI on standard input, never in its arguments.
+ */
+export const registerDevelopmentClient = (options: DevelopmentClientOptions) =>
+  Effect.gen(function* () {
+    const { convex } = options;
+    const names = convex(["env", "list", "--names-only"]).split("\n");
+    if (HUB_VARIABLES.every((name) => names.includes(name))) return undefined;
+    const siteUrl = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.String))(
+      convex(["run", "--inline-query", "process.env.CONVEX_SITE_URL"]),
+    ).pipe(
+      Effect.mapError(
+        () => new HubClientFailed({ team: options.team, reason: "no CONVEX_SITE_URL to register" }),
+      ),
+    );
+    const callbackUrl = `${siteUrl.replace(/\/$/, "")}${options.callbackPath}`;
+    const client = yield* registerHubClient(yield* ManagementApi, {
+      team: options.team,
+      app: options.app,
+      redirectUri: callbackUrl,
+      deploymentType: "development",
+      clientName: "development",
+      softwareVersion: new URL(siteUrl).host,
+    });
+    // One request, so that an interrupted run cannot leave half a client. `--force` replaces the
+    // values of an earlier one.
+    convex(
+      ["env", "set", "--force"],
+      `HUB_ISSUER='${client.issuer}'\nHUB_CLIENT_ID='${client.clientId}'\nHUB_CLIENT_SECRET='${Redacted.value(client.clientSecret)}'\n`,
+    );
+    return callbackUrl;
+  });

package/src/Providers.ts

@@ -4,6 +4,7 @@ import * as Provider from "alchemy/Provider";
 import * as Layer from "effect/Layer";
 import { type Credentials, fromConfig } from "./Credentials.ts";
 import { DeploymentProvider, DeploymentResource } from "./Deployment.ts";
+import { HubClient, HubClientProvider } from "./HubClient.ts";
 import { ManagementApiLive } from "./ManagementApi.ts";
 import { Project, ProjectProvider } from "./Project.ts";
 
@@ -15,8 +16,8 @@ export class Providers extends Provider.ProviderCollection<Providers>()("Convex"
  * `CONVEX_DEPLOY_KEY`).
  */
 export const providers = (credentials: Layer.Layer<Credentials> = fromConfig()) =>
-  Layer.effect(Providers, Provider.collection([Project, DeploymentResource])).pipe(
-    Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider())),
+  Layer.effect(Providers, Provider.collection([Project, DeploymentResource, HubClient])).pipe(
+    Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider(), HubClientProvider())),
     Layer.provide(ManagementApiLive()),
     Layer.provide(credentials),
     Layer.orDie,

package/src/State.ts

@@ -1,36 +1,33 @@
 // Alchemy state in Convex: `state: Convex.state({ team })` in `Alchemy.Stack`.
 //
-// One project for each Convex team, `samebase`, holds the state of
+// One project for each Convex team, `alchemy-state-store`, holds the state of
 // every stack and stage of the team in its production deployment: the
 // tables `resources (stack, stage, fqn, value)` and `outputs (stack, stage,
 // value)` of the alchemyState component (src/store/component), served by the
-// functions of src/store/functions.ts. Two apps serve them: the store app of
-// src/store/convex (a seed), which this provider pushes, and the base app of
-// the team (a base), which mounts the component next to its own components.
-// The store lives outside every resource that a stack manages, so a stack
-// can create and destroy its own project. See docs/design/convex-state.md.
+// functions of src/store/convex. The store lives
+// outside every resource that a stack manages, so a stack can create and
+// destroy its own project. See docs/design/convex-state.md.
 //
 // Bootstrap, on the first call of the run: the team token (CONVEX_ACCESS_TOKEN,
 // or the Convex CLI login) finds the project by name, or creates it; a deploy
 // key of its production deployment that can run internal queries and
 // mutations, and nothing else, is created for the run and deleted at its
-// end; the `state:version` query says the store version and the app that
-// serves it. Without one, or with an older seed, the installed Convex CLI
-// pushes src/store/convex to it, with a push key that is deleted after the
-// push. An older base fails the run: a push of the store app would erase the
-// base app. The raw state functions are internal; authenticated readers get
+// end; the `state:version` query says whether the deployment has the store
+// of this version. Without one, or with an older one, the installed Convex
+// CLI pushes src/store/convex to it, with a push key that is deleted after
+// the push. The raw state functions are internal; authenticated readers get
 // repository-scoped subscriptions with secret values removed. A key that stops working during a
 // long run (it expires after two hours) is replaced once per call.
 //
-// Two first runs of a team can both create a project named `samebase`.
+// Two first runs of a team can both create a project named `alchemy-state-store`.
 // The run whose project is not the oldest deletes its own, before it writes
 // anything, and uses the oldest: both runs end on one store.
 //
 // Samebase reads `stacks`, `getOutput`, `readStack`, and `reader:repository`
-// by name. STORE_VERSION is the wire contract: it rises only when a function
-// that a released client calls changes or goes away, and a client works only
-// with a store of its own version. An older seed is pushed over; an older base
-// and a newer store fail the run.
+// by name. The store and its readers are released and upgraded together:
+// STORE_VERSION rises with each change of a function, and a client works only
+// with a store of its own version. An older store is pushed over; a newer one
+// fails the run.
 //
 // The stage output that `setOutput` stores is the stack's output plus the
 // run record of src/RunRecord.ts under the key `samebase.run`: the
@@ -83,7 +80,7 @@ import { type RunRecord, runRecord, withRunRecord } from "./RunRecord.ts";
 import { STORE_VERSION } from "./store/convex/version.ts";
 
 /** The name of the state project in each team. */
-export const STORE_PROJECT_NAME = "samebase";
+export const STORE_PROJECT_NAME = "alchemy-state-store";
 
 /**
  * The actions of the key of one run: the internal queries and mutations of
@@ -244,39 +241,6 @@ const storeVersion = (api: FunctionApi) =>
       ),
     );
 
-/**
- * The app that serves the store. A store without `state:host` is a seed: it
- * was pushed before 0.14.0, and only the store app of this package served
- * those stores.
- */
-const storeHost = (api: FunctionApi) =>
-  api
-    .call("state:host", {})
-    .pipe(
-      Effect.flatMap((reply) =>
-        reply.status === "error" && MISSING_FUNCTION.test(reply.errorMessage)
-          ? Effect.succeed("seed" as const)
-          : valueOf(reply).pipe(
-              Effect.flatMap(decode(Schema.Literals(["seed", "base"]), "store host")),
-            ),
-      ),
-    );
-
-/**
- * The base app of the team serves an older store. Convex.state() never
- * pushes its store app over a base, because the push replaces every function
- * of the deployment and so erases the base app.
- */
-export class OutdatedBase extends Schema.TaggedError<OutdatedBase>()("OutdatedBase", {
-  team: Schema.Union([Schema.String, Schema.Number]),
-  deployment: Schema.String,
-  version: Schema.Number,
-}) {
-  override get message() {
-    return `The base of team ${this.team} (${this.deployment}) answers store version ${this.version}, and this package needs store version ${STORE_VERSION}. Convex.state does not push over a base. Upgrade the dependency @samebase/alchemy-convex of the base app to the version of this package, and push the base app.`;
-  }
-}
-
 /**
  * The functions directory of the store app, `src/store/convex` of this
  * package. This file is `src/State.ts` in a checkout and a chunk in `lib/`
@@ -288,7 +252,7 @@ export const storeDirectory = () =>
   join(dirname(fileURLToPath(import.meta.url)), "..", "src", "store", "convex");
 
 export interface StoreOptions {
-  /** Team slug or numeric team id of the `samebase` project, or undefined with a team access token, which names its team. */
+  /** Team slug or numeric team id of the `alchemy-state-store` project, or undefined with a team access token, which names its team. */
   readonly team: string | number | undefined;
   readonly api: ManagementApiService;
   readonly spawner: ChildProcessSpawner.ChildProcessSpawner["Service"];
@@ -365,9 +329,9 @@ const createStoreProject = (api: ManagementApiService, teamId: number, team: str
   });
 
 /**
- * The StateService over the `samebase` project of the team: found or
- * created, its store app pushed when the store is missing or an older seed,
- * and read and written with the keys of this run.
+ * The StateService over the `alchemy-state-store` project of the team: found or
+ * created, its store pushed when it is missing or older, and read and
+ * written with the keys of this run.
  */
 export const makeConvexState = (options: StoreOptions) =>
   Effect.gen(function* () {
@@ -415,38 +379,22 @@ export const makeConvexState = (options: StoreOptions) =>
         ),
     };
 
-    // The store app is pushed only over no store or an older seed. A base
-    // serves the same functions, and a push would erase the base app.
-    const needsPush = (found: number | undefined) =>
-      found === undefined
-        ? Effect.succeed(true)
-        : found < STORE_VERSION
-          ? storeHost(functions).pipe(Effect.map((host) => host === "seed"))
-          : Effect.succeed(false);
     let version = yield* storeVersion(functions);
-    if (yield* needsPush(version)) {
+    if (version === undefined || version < STORE_VERSION) {
       // Code without `state:version` is another app with the name of the store.
       if (version === undefined && deployment.lastDeployTime) {
         return yield* failure(
           `project ${STORE_PROJECT_NAME} (${project.id}) of team ${team} has code that is not the state store, and Convex.state does not push over it. Rename that project in the Convex dashboard.`,
         );
       }
-      // Another run can push a newer store, or the base app, in the meantime:
-      // read again right before the push. The push itself has no lock (see
-      // the design note).
+      // Another run can push a newer store in the meantime: read again right
+      // before the push. The push itself has no lock (see the design note).
       version = yield* storeVersion(functions);
-      if (yield* needsPush(version)) {
+      if (version === undefined || version < STORE_VERSION) {
         yield* pushStore(options, deployment);
         version = yield* storeVersion(functions);
       }
     }
-    if (
-      version !== undefined &&
-      version < STORE_VERSION &&
-      (yield* storeHost(functions)) === "base"
-    ) {
-      return yield* new OutdatedBase({ team, deployment: deployment.name, version });
-    }
     if (version !== STORE_VERSION) {
       return yield* failure(
         `${deployment.name} answers store version ${version ?? "none"}, and this package needs store version ${STORE_VERSION}.`,
@@ -493,12 +441,11 @@ export const makeConvexState = (options: StoreOptions) =>
   });
 
 /**
- * Alchemy state in the `samebase` project of `team`, with the team token
+ * Alchemy state in the `alchemy-state-store` project of `team`, with the team token
  * in CONVEX_ACCESS_TOKEN or the Convex CLI login. A team access token names
  * its team, so `team` is optional with one; the Convex CLI login needs the
  * slug or the id. The first use of the run finds or creates the project and
- * pushes the store app when the store is missing or an older seed. An older
- * base fails the run with {@link OutdatedBase}. `alchemy plan` on another
+ * pushes the store when it is missing or older. `alchemy plan` on another
  * stack never touches Convex.
  */
 export const state = (

package/src/cli.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// The command of the package:
+//
+//   alchemy-convex hub-client --team <team> --app <app> --callback-path <path>
+//
+// It runs in the directory of a Convex app, and gives the development deployment of that directory
+// a client of the identity hub of the team: see registerDevelopmentClient. It uses
+// CONVEX_ACCESS_TOKEN or the Convex CLI login.
+import { execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { fromConfig } from "./Credentials.ts";
+import { registerDevelopmentClient } from "./HubClient.ts";
+import { ManagementApiLive } from "./ManagementApi.ts";
+import { installedCli } from "./Push.ts";
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  options: {
+    team: { type: "string" },
+    app: { type: "string" },
+    "callback-path": { type: "string" },
+  },
+});
+const { team, app, "callback-path": callbackPath } = values;
+if (
+  positionals.join(" ") !== "hub-client" ||
+  team === undefined ||
+  app === undefined ||
+  callbackPath === undefined
+) {
+  console.error(
+    "Usage: alchemy-convex hub-client --team <team> --app <app> --callback-path <path>",
+  );
+  process.exit(1);
+}
+
+const program = Effect.gen(function* () {
+  const [command, ...prefix] = yield* installedCli(process.cwd());
+  const callbackUrl = yield* registerDevelopmentClient({
+    team,
+    app,
+    callbackPath,
+    convex: (args, input) =>
+      execFileSync(command, [...prefix, ...args], {
+        encoding: "utf8",
+        input,
+        stdio: ["pipe", "pipe", "inherit"],
+      }).trim(),
+  });
+  console.log(
+    callbackUrl === undefined
+      ? "Hub client already registered."
+      : `Hub client registered for ${callbackUrl}.`,
+  );
+}).pipe(Effect.provide(ManagementApiLive().pipe(Layer.provide(fromConfig()))));
+
+await Effect.runPromise(program).catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/index.ts

@@ -18,6 +18,14 @@ export {
   type DeploymentProps,
   ProductionDeploymentNotFound,
 } from "./Deployment.ts";
+export {
+  HUB_PROJECT_NAME,
+  HubClient,
+  type HubClientAttributes,
+  HubClientFailed,
+  type HubClientProps,
+  type HubDeploymentType,
+} from "./HubClient.ts";
 export { ConvexApiError, ManagementApi } from "./ManagementApi.ts";
 export {
   AmbiguousProject,
@@ -38,7 +46,7 @@ export {
   runRecord,
   withRunRecord,
 } from "./RunRecord.ts";
-export { OutdatedBase, state, STORE_PROJECT_NAME } from "./State.ts";
+export { state, STORE_PROJECT_NAME } from "./State.ts";
 export {
   CodePushFailed,
   ConvexAppNotFound,

package/src/store/component/reader.ts

@@ -3,7 +3,7 @@
 // `ctx.auth`.
 import { v, type Infer } from "convex/values";
 import { query } from "./_generated/server.js";
-import { runRecord, validate } from "./runRecord.js";
+import { runRecord, validate } from "./runRecord.ts";
 
 const stage = v.object({
   name: v.string(),

package/src/store/component/schema.ts

@@ -1,6 +1,6 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
-import { runRecord } from "./runRecord.js";
+import { runRecord } from "./runRecord.ts";
 
 // `value` is the JSON text of Alchemy's encodeState(...): the same text that
 // Alchemy's local state writes to a file. A Convex object would reject keys

package/src/store/component/state.ts

@@ -8,7 +8,7 @@
 import { v, type Infer } from "convex/values";
 import type { MutationCtx, QueryCtx } from "./_generated/server.js";
 import { mutation, query } from "./_generated/server.js";
-import { runRecord } from "./runRecord.js";
+import { runRecord } from "./runRecord.ts";
 
 const stage = { stack: v.string(), stage: v.string() };
 const resource = { ...stage, fqn: v.string() };

package/src/store/convex/auth.config.ts

@@ -1,4 +1,14 @@
-import { authConfig } from "../authConfig.js";
+import type { AuthConfig } from "convex/server";
 import { env } from "./_generated/server.js";
 
-export default authConfig(env.CONVEX_CLOUD_URL);
+export default {
+  providers: [
+    {
+      type: "customJwt",
+      issuer: env.CONVEX_CLOUD_URL,
+      applicationID: `${env.CONVEX_CLOUD_URL}/alchemy-reader`,
+      jwks: `${env.CONVEX_CLOUD_URL}/.well-known/jwks.json`,
+      algorithm: "ES256",
+    },
+  ],
+} satisfies AuthConfig;

package/src/store/convex/convex.config.ts

@@ -1,5 +1,5 @@
 import { defineApp } from "convex/server";
-import alchemyState from "../component/convex.config.js";
+import alchemyState from "../component/convex.config.ts";
 
 const app = defineApp();
 app.use(alchemyState);

package/src/store/convex/reader.ts

@@ -1,5 +1,51 @@
-// The authenticated, redacted reads of the store app, from src/store/functions.ts.
-import { readerFunctions } from "../functions.js";
+// Authenticated reads stay in the app: `authorize` signs and `repository`
+// verifies with `ctx.auth`, which a component does not have. The rows and the
+// redaction are in the alchemyState component.
+import { v } from "convex/values";
+import { repositoryReply } from "../component/reader.ts";
 import { components } from "./_generated/api.js";
+import { env, internalMutation, query } from "./_generated/server.js";
 
-export const { authorize, repository } = readerFunctions(components.alchemyState);
+const repositoryName = /^[^/]+\/[^/]+$/;
+
+/** Only a deployment credential can exchange an approved repository for a read token. */
+export const authorize = internalMutation({
+  args: { repository: v.string(), subject: v.string() },
+  returns: v.object({ token: v.string() }),
+  handler: async (ctx, args) => {
+    if (!repositoryName.test(args.repository) || args.subject === "") {
+      throw new Error("A repository and subject are required.");
+    }
+    return {
+      token: await ctx.auth.signJwt({
+        expiresInSeconds: 300,
+        claims: {
+          sub: args.subject,
+          aud: `${env.CONVEX_CLOUD_URL}/alchemy-reader`,
+          repository: args.repository,
+          scope: "alchemy:read",
+        },
+      }),
+    };
+  },
+});
+
+/** A native subscription reads only the repository named in its verified capability. */
+export const repository = query({
+  args: {},
+  returns: repositoryReply,
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (
+      identity === null ||
+      identity.scope !== "alchemy:read" ||
+      typeof identity.repository !== "string" ||
+      !repositoryName.test(identity.repository)
+    ) {
+      throw new Error("Alchemy repository read access is required.");
+    }
+    return await ctx.runQuery(components.alchemyState.reader.repository, {
+      repository: identity.repository,
+    });
+  },
+});