@samebase/alchemy-convex 0.23.0 → 0.25.0

package/README.md

@@ -302,23 +302,29 @@ call.
 - `Convex.HubClient`: `{ team, app, redirectUri, deploymentType, clientName, softwareVersion? }`
   registers one deployment as a client of the identity hub of the team. The hub is the production
   deployment of the project `identity-hub`. The resource finds it by name and runs its internal
-  function `identityBroker:registerClient` with a short-lived key, so the stack needs no other
-  credential and no hub address. The first client of an `app` creates the app. Outputs `issuer`,
-  `clientId`, `clientSecret`, `redirectUri`, `deploymentType`, and `clientName`, which the `env` of
-  the `Convex.Deployment` writes to the deployment. Another `redirectUri` is a new client, and a
-  destroy deletes the client.
+  functions `identityBroker:renewClient` and `identityBroker:registerClient` with a short-lived key,
+  so the stack needs no other credential and no hub address. The first client of an `app` creates
+  the app. Outputs `issuer`, `clientId`, `clientSecret`, `redirectUri`, `deploymentType`, and
+  `clientName`, which the `env` of the `Convex.Deployment` writes to the deployment.
+  - Each deploy renews the client on the hub. A preview or development client expires 14 days after
+    its last deploy or use, and a production client never expires. A client that the hub no longer
+    has gets a new one in the same run.
+  - Another `redirectUri` is a new client, and the old one goes.
+  - A destroy deletes a preview or development client. It does nothing to a production client,
+    because the production deployment can stay.
 
 - `Convex.SharedHubClient`: `{ app, redirectUri, deploymentType, softwareVersion? }` gets a client
-  of the central identity hub through samebase.com, for an app that deploys in its own GitHub
-  Actions run, on any host. The workflow needs `permissions: id-token: write` and no Samebase key.
-  The origin of `redirectUri` must serve `/samebase-verification.json` with the numeric GitHub id of
-  the repository, `{ "repository": "123" }`, which `gh api repos/<owner>/<name> --jq .id` prints.
-  Samebase reads it before it registers the client, so the site must be live first. Outputs
-  `status`, `issuer`, `clientId`, `clientSecret`, `registrationAccessToken`,
-  `registrationClientUri`, `deploymentType`, and `redirectUri`.
+  of the central identity hub, for an app that deploys in its own GitHub Actions run, on any host.
+  The workflow needs `permissions: id-token: write`, and no key and no Samebase account. `app` is at
+  most 64 characters. The origin of `redirectUri` must serve `/samebase-verification.json` with the
+  numeric GitHub id of the repository, `{ "repository": "123" }`, which
+  `gh api repos/<owner>/<name> --jq .id` prints. The hub reads it before it registers the client, so
+  the site must be live first. Outputs `status`, `issuer`, `clientId`, `clientSecret`,
+  `registrationAccessToken`, `registrationClientUri`, `deploymentType`, and `redirectUri`.
   - Each deploy reads the saved client on the hub with its own token. A client that is gone gets a
     new one, and a client on another `redirectUri` too.
-  - A refusal logs its reason, such as a host that does not serve the file.
+  - A new client logs the link to the terms of the shared sign-in service. A refusal logs its
+    reason, such as a host that does not serve the file, a block, or the hourly limit it reached.
   - No failure stops a deploy or a destroy. A failed renewal keeps the saved values. Without saved
     values, `status` is `off`, and `issuer`, `clientId`, and `clientSecret` are the `no-hub` values
     of a checkout without a hub. A run without a GitHub OIDC token, such as on a laptop, does the
@@ -326,12 +332,14 @@ call.
   - `status` is `suspended` when the hub suspended the client. The client keeps its values.
   - A destroy deletes a preview client. It does nothing to a production client, because the
     production deployment can stay.
-  - `SAMEBASE_URL` replaces `https://samebase.com`.
+  - `HUB_URL` replaces `https://auth.samebase.com`, the hub that the run asks at `/hub-clients`.
 
 A development deployment has no stack, so the package has a command for it. Run it in the directory
-of the app, before the first push: it registers the deployment of that directory with
-`CONVEX_ACCESS_TOKEN` or the Convex CLI login, and writes `HUB_ISSUER`, `HUB_CLIENT_ID`, and
-`HUB_CLIENT_SECRET` to it. A deployment with all three variables keeps them.
+of the app, before the first push and at each dev start, with `CONVEX_ACCESS_TOKEN` or the Convex
+CLI login. It renews the client that `HUB_CLIENT_ID` names, so the client expires 14 days after the
+last dev start or use. A deployment without all three variables, or whose client the hub no longer
+has, gets a new client, and the command writes `HUB_ISSUER`, `HUB_CLIENT_ID`, and
+`HUB_CLIENT_SECRET` to it.
 
 ```sh
 npx alchemy-convex hub-client --team my-team --app scout --callback-path /auth/hub/callback

package/lib/{HubClient-B6hjkbjW.js → HubClient-Bs5_j18U.js}

@@ -1846,6 +1846,8 @@ const Registered = Schema.Struct({
 	clientId: Schema.NonEmptyString,
 	clientSecret: Schema.NonEmptyString
 });
+/** The reply of `identityBroker:renewClient`: false when the hub no longer has the client. */
+const Renewed = Schema.Boolean;
 /** Runs `use` with the function API of the hub of `team`, with a key of this call only. */
 const withHub = (api, team, use) => Effect.gen(function* () {
 	const teamId = yield* api.resolveTeamId(team);
@@ -1870,8 +1872,9 @@ const runHub = (functions, team, name, args) => functions.call(`identityBroker:$
 	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.
+* Registers one client, which expires unless it is a production client. An
+* attempt that a lost reply repeats leaves one spare client on the hub, which
+* signs nobody in, and which the hub deletes after 14 days.
 */
 const registerHubClient = (api, props) => withHub(api, props.team, (functions) => runHub(functions, props.team, "registerClient", {
 	appId: props.app,
@@ -1879,7 +1882,8 @@ const registerHubClient = (api, props) => withHub(api, props.team, (functions) =
 	deploymentType: props.deploymentType,
 	clientName: props.clientName,
 	softwareVersion: props.softwareVersion ?? "unknown",
-	tokenEndpointAuthMethod: "client_secret_post"
+	tokenEndpointAuthMethod: "client_secret_post",
+	expires: true
 })).pipe(Effect.flatMap((value) => Schema.decodeUnknownEffect(Registered)(value).pipe(Effect.mapError(() => new HubClientFailed({
 	team: props.team,
 	reason: "registerClient gave no client"
@@ -1888,18 +1892,36 @@ const registerHubClient = (api, props) => withHub(api, props.team, (functions) =
 	clientId,
 	clientSecret: Redacted.make(clientSecret)
 })));
+/**
+* Renews one client: true while the hub has it. A preview or development client
+* then expires 14 days after this call.
+*/
+const renewHubClient = (api, team, clientId) => withHub(api, team, (functions) => runHub(functions, team, "renewClient", {
+	clientId,
+	expires: true
+})).pipe(Effect.flatMap((value) => Schema.decodeUnknownEffect(Renewed)(value).pipe(Effect.mapError(() => new HubClientFailed({
+	team,
+	reason: "renewClient gave no answer"
+})))));
+/**
+* Renews a client whose values the caller holds: false only when the hub answers that the client is
+* gone. Any other failure, such as a hub or a Convex API that cannot answer, keeps the client and
+* warns, so an outage never stops a deploy or a dev start; the next one renews it.
+*/
+const renewOrKeep = (api, team, clientId) => renewHubClient(api, team, clientId).pipe(Effect.catch((error) => Effect.logWarning(`Convex.HubClient: ${clientId} keeps its saved values, because the hub could not renew it: ${error.message}`).pipe(Effect.as(true))));
 const unregister = (api, team, clientId) => 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, props) => output.redirectUri === props.redirectUri && output.deploymentType === props.deploymentType;
 const HubClientProvider = () => Provider.effect(HubClient, Effect.gen(function* () {
 	const api = yield* ManagementApi;
 	return {
-		diff: ({ news, olds, output }) => Effect.succeed(!isResolved(news) || output === void 0 ? void 0 : !registeredFor(output, news) ? { action: "replace" } : olds.team === news.team && olds.app === news.app ? { action: "noop" } : { action: "update" }),
+		diff: ({ news }) => Effect.succeed(isResolved(news) ? { action: "update" } : void 0),
 		read: ({ output }) => Effect.succeed(output),
 		reconcile: Effect.fn(function* ({ news, output }) {
-			if (output !== void 0 && registeredFor(output, news)) return output;
+			const saved = output !== void 0 && registeredFor(output, news) ? output : void 0;
+			if (saved !== void 0 && (yield* renewOrKeep(api, news.team, saved.clientId))) return saved;
 			const client = yield* registerHubClient(api, news);
-			if (output !== void 0) 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\`.`)));
+			if (output !== void 0 && saved === void 0) 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,
@@ -1907,17 +1929,20 @@ const HubClientProvider = () => Provider.effect(HubClient, Effect.gen(function*
 				clientName: news.clientName
 			};
 		}),
-		delete: ({ olds, output }) => unregister(api, olds.team, output.clientId).pipe(Effect.asVoid)
+		delete: ({ olds, output }) => output.deploymentType === "production" ? Effect.void : unregister(api, olds.team, output.clientId).pipe(Effect.asVoid)
 	};
 }));
 /**
 * `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.
+* development deployment, which no stack deploys. Run it at each dev start: it renews the client
+* that the three variables name, so the client expires 14 days after the last dev start or use. A
+* deployment without all three variables, or whose client the hub no longer has, such as one with
+* the `no-hub` values, gets a new client. Answers the callback URL of a new client, or undefined
+* for a renewal. The secret reaches the Convex CLI on standard input, never in its arguments.
 */
 const registerDevelopmentClient = (options) => Effect.gen(function* () {
 	const { convex } = options;
+	const api = yield* ManagementApi;
 	const envPrefix = options.envPrefix ?? "HUB";
 	const variables = [
 		`${envPrefix}_ISSUER`,
@@ -1929,7 +1954,14 @@ const registerDevelopmentClient = (options) => Effect.gen(function* () {
 		"list",
 		"--names-only"
 	]).split("\n");
-	if (variables.every((name) => names.includes(name))) return void 0;
+	if (variables.every((name) => names.includes(name))) {
+		const clientId = convex([
+			"env",
+			"get",
+			`${envPrefix}_CLIENT_ID`
+		]);
+		if (yield* renewOrKeep(api, options.team, clientId)) return void 0;
+	}
 	const siteUrl = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.String))(convex([
 		"run",
 		"--inline-query",
@@ -1939,7 +1971,7 @@ const registerDevelopmentClient = (options) => Effect.gen(function* () {
 		reason: "no CONVEX_SITE_URL to register"
 	})));
 	const callbackUrl = `${siteUrl.replace(/\/$/, "")}${options.callbackPath}`;
-	const client = yield* registerHubClient(yield* ManagementApi, {
+	const client = yield* registerHubClient(api, {
 		team: options.team,
 		app: options.app,
 		redirectUri: callbackUrl,
@@ -1957,4 +1989,4 @@ const registerDevelopmentClient = (options) => Effect.gen(function* () {
 //#endregion
 export { PushTargetMismatch as A, DEPLOY_KEY_ENV as B, DeploymentProvider as C, ConvexAppNotFound as D, CodePushFailed as E, ManagementApi as F, fromValues as H, ManagementApiLive as I, ACCESS_TOKEN_ENV as L, installedCli as M, parseDeployOutput as N, ConvexCliNotFound as O, ConvexApiError as P, Credentials as R, DeploymentIdentityChange as S, ProductionDeploymentNotFound as T, fromConfig as V, ProjectProvider as _, registerDevelopmentClient as a, AmbiguousDeployment as b, RUN_RECORD_KEY as c, withRunRecord as d, AmbiguousProject as f, ProjectNotFound as g, ProjectDeploymentChange as h, HubClientProvider as i, VariablesOwnedBySomeoneElse as j, EnvironmentNeedsDeployKey as k, RunRecordError as l, Project as m, HubClient as n, STORE_PROJECT_NAME as o, CreatedProjectNotFound as p, HubClientFailed as r, state as s, HUB_PROJECT_NAME as t, runRecord as u, ProjectTeamChange as v, DeploymentResource as w, Deployment as x, AbsoluteRootDir as y, CredentialsError as z };
 
-//# sourceMappingURL=HubClient-B6hjkbjW.js.map
+//# sourceMappingURL=HubClient-Bs5_j18U.js.map