@gjermundgaraba/clankerauth 0.22.0 → 0.23.0

package/dist/main.mjs

@@ -15,67 +15,88 @@ import { dirname, join } from "node:path";
 import { createServer } from "node:http";
 import * as oauth from "oauth4webapi";
 //#region ../../packages/admin-api/dist/index.js
-var BadRequest = class extends Schema.TaggedError()("BadRequest", { error: Schema.String }, { httpApiStatus: 400 }) {};
-var NotFound = class extends Schema.TaggedError()("NotFound", { error: Schema.String }, { httpApiStatus: 404 }) {};
-var Conflict = class extends Schema.TaggedError()("Conflict", { error: Schema.String }, { httpApiStatus: 409 }) {};
-var TooManyRequests = class extends Schema.TaggedError()("TooManyRequests", { error: Schema.String }, { httpApiStatus: 429 }) {};
-/** The schema defines the public response; the diagnostic cause reaches logs, never a caller. */
-var InternalServerError = class extends Schema.TaggedError()("InternalServerError", { error: Schema.String }, { httpApiStatus: 500 }) {
-	cause;
-};
-var ServiceUnavailable = class extends Schema.TaggedError()("ServiceUnavailable", { error: Schema.String }, { httpApiStatus: 503 }) {};
 /**
-* What every action may fail with, beside effect-actions' built-in `InvalidInput`,
-* `Unauthenticated` and `Forbidden`, which every endpoint and tool declares.
+* This issuer's own fault: a failed query, an unreadable row, an unexpected provider failure.
+* The schema defines the public response; the diagnostic cause reaches logs, never a caller.
 */
-const errors = [
-	BadRequest,
-	NotFound,
-	Conflict,
-	TooManyRequests,
-	InternalServerError,
-	ServiceUnavailable
-];
-[...errors, Action.Forbidden];
+var InternalServerError = class InternalServerError extends Schema.TaggedError()("InternalServerError", { message: Schema.String }, { httpApiStatus: 500 }) {
+	cause;
+	static of = (cause) => {
+		const error = new InternalServerError({ message: "Request could not be completed" });
+		error.cause = cause;
+		return error;
+	};
+};
+/** The issuer could not decide the request now, such as when its session store is unreachable. */
+var ServiceUnavailable = class extends Schema.TaggedError()("ServiceUnavailable", { message: Schema.String }, { httpApiStatus: 503 }) {};
+var ClientNotFound = class ClientNotFound extends Schema.TaggedError()("ClientNotFound", {
+	clientId: Schema.String,
+	message: Schema.String
+}, { httpApiStatus: 404 }) {
+	static of = (clientId) => new ClientNotFound({
+		clientId,
+		message: `No client ${clientId} is registered`
+	});
+};
+var ResourceNotFound = class ResourceNotFound extends Schema.TaggedError()("ResourceNotFound", {
+	identifier: Schema.String,
+	message: Schema.String
+}, { httpApiStatus: 404 }) {
+	static of = (identifier) => new ResourceNotFound({
+		identifier,
+		message: `No resource ${identifier} exists`
+	});
+};
+var ApiKeyNotFound = class ApiKeyNotFound extends Schema.TaggedError()("ApiKeyNotFound", {
+	keyId: Schema.String,
+	message: Schema.String
+}, { httpApiStatus: 404 }) {
+	static of = (keyId) => new ApiKeyNotFound({
+		keyId,
+		message: `No API key ${keyId} exists`
+	});
+};
 /**
-* The owner administering the issuer, as its authentication verified the request: what every
-* administration action states, `caller: CurrentOwner`. Never supplied by action arguments or
-* at startup.
+* The client registered itself, through DCR or CIMD: the owner can revoke, block or delete it,
+* but its access and registration are its own, and consent decides what it gets.
 */
+var ClientIsAutomatic = class ClientIsAutomatic extends Schema.TaggedError()("ClientIsAutomatic", {
+	clientId: Schema.String,
+	message: Schema.String
+}, { httpApiStatus: 409 }) {
+	static of = (clientId) => new ClientIsAutomatic({
+		clientId,
+		message: `Client ${clientId} registered itself; revoke, block or delete it instead`
+	});
+};
+/** First-run setup has already created the owner. */
+var OwnerExists = class OwnerExists extends Schema.TaggedError()("OwnerExists", { message: Schema.String }, { httpApiStatus: 409 }) {
+	static of = () => new OwnerExists({ message: "Setup already completed" });
+};
+/** The provider refused the request's input on a rule of its own, which `message` states. */
+var ProviderRefused = class extends Schema.TaggedError()("ProviderRefused", { message: Schema.String }, { httpApiStatus: 400 }) {};
+/** A request body the issuer could not read, on a route that is not an action. */
+var UnreadableRequest = class extends Schema.TaggedError()("UnreadableRequest", { message: Schema.String }, { httpApiStatus: 400 }) {};
+const undecided = [ServiceUnavailable, InternalServerError];
 var CurrentOwner = class extends Context.Service()("clankerauth/CurrentOwner") {};
-/**
-* The dashboard's owner session: the issuer's session cookie, named `cookie`, which the browser
-* sends. The provider names that cookie by the deployment, `__Secure-` prefixed over HTTPS, so
-* the server builds this descriptor where it starts, from the name its sessions use, and builds
-* both its binding and its `Authentication.layer` from it: that layer serves only a binding
-* built from that very descriptor, not another naming the same cookie. A browser's binding,
-* from `OwnerSession`, only calls. Its verifier reads the session through the provider, so it
-* may fail as an action does, with any of `errors`, such as `ServiceUnavailable`, answered with
-* its own status.
-*/
 const ownerSession = (cookie) => Authentication.make("clankerauth.OwnerSession", CurrentOwner, {
 	security: HttpApiSecurity.apiKey({
 		in: "cookie",
 		key: cookie
 	}),
-	error: errors
+	error: undecided
 });
-/**
-* The browser's owner session. A page never needs the cookie's name, as the browser sends its
-* cookies itself: this one names the provider's cookie over plain HTTP, which only the server
-* would read.
-*/
 const OwnerSession = ownerSession("better-auth.session_token");
-/**
-* An administration client's OAuth access token for the issuer's origin root, `<baseURL>/`,
-* over MCP or `OwnerHttp`. Its verifier reads the token's owner and client from the database,
-* so it may fail as an action does, with any of `errors`: `ServiceUnavailable` when the token
-* cannot be decided, or `InternalServerError`.
-*/
-const OwnerToken = Authentication.make("clankerauth.OwnerToken", CurrentOwner, { error: errors });
+const OwnerToken = Authentication.make("clankerauth.OwnerToken", CurrentOwner, { error: undecided });
+const administrationIdentifier = (origin) => new URL("/", origin).href;
+const administrationScopes = {
+	read: "clankerauth:read",
+	write: "clankerauth:write"
+};
+const passwordRule = `Passwords have 8 to 128 characters`;
 const SetupInput = Schema.Struct({
-	email: Schema.String,
-	password: Schema.String
+	email: Schema.String.check(Schema.isPattern(/\S/u, { message: "Setup requires an email" })),
+	password: Schema.String.check(Schema.isMinLength(8, { message: passwordRule }), Schema.isMaxLength(128, { message: passwordRule }))
 });
 const ClientAuthMethod = Schema.Literals([
 	"none",
@@ -85,7 +106,7 @@ const ClientAuthMethod = Schema.Literals([
 const ApplicationType = Schema.Literals(["web", "native"]);
 /** The resources a managed client may obtain, each named once. */
 const ResourceSelection = Schema.Array(Schema.String).check(Schema.isUnique({ message: "Choose unique Resources" }));
-/** Provider vocabulary: the server passes these fields through unchanged. */
+/** The provider's registration fields, passed through unchanged, and the client's `resources`. */
 const ClientInput = Schema.Struct({
 	client_name: Schema.String,
 	redirect_uris: Schema.Array(Schema.String),
@@ -93,7 +114,6 @@ const ClientInput = Schema.Struct({
 	token_endpoint_auth_method: ClientAuthMethod,
 	application_type: ApplicationType
 });
-/** The provider's update endpoint cannot change the authentication method. */
 const ClientUpdateInput = Schema.Struct({
 	client_id: Schema.String,
 	client_name: Schema.String,
@@ -135,11 +155,6 @@ const Resource = Schema.Struct({
 	scopes: Schema.Array(Schema.String)
 });
 const ResourceSummary = Resource.pipe(Schema.fieldsAssign({ builtIn: Schema.Boolean }));
-/**
-* A resource as the owner writes it. The issuer trims each field before storing it, so the
-* rules allow surrounding whitespace: a name that is not blank, and scopes that are OAuth
-* scope tokens (RFC 6749 §3.3). Stored resources are `Resource`, which carries no rule.
-*/
 const ResourceInput = Schema.Struct({
 	identifier: Schema.String,
 	name: Schema.String.check(Schema.isPattern(/\S/u, { message: "Resources require a name" })),
@@ -164,11 +179,6 @@ const KeyPermissions = Schema.Record(Schema.String, Schema.Array(Schema.String))
 const KeyGrants = Schema.Record(Schema.String, Schema.Array(Schema.String).check(Schema.isMinLength(1, { message: "Select explicitly granted, currently available Resource scopes" }), Schema.isUnique({ message: "Select explicitly granted, currently available Resource scopes" }))).check(Schema.isMinProperties(1, { message: "Select at least one Resource and scope" }));
 /** A key's name as the owner writes it; the issuer stores it trimmed. */
 const KeyName = Schema.String.check(Schema.isMaxLength(100, { message: "Key names require 1–100 characters" }), Schema.isPattern(/\S/u, { message: "Key names require 1–100 characters" }));
-/**
-* Timestamps stay ISO strings on the wire and arrive as `DateTime.Utc` values. An input
-* without an offset is read as UTC, so the instant an API caller means never depends on
-* the host's time zone; every value this issuer writes carries `Z`.
-*/
 const Timestamp = Schema.DateTimeUtcFromString;
 /**
 * What a client holds for one resource: a consent, a live refresh token, or both. A
@@ -195,7 +205,7 @@ const ApiKeyUpdate = Schema.Struct({
 	permissions: Schema.optional(KeyGrants),
 	enabled: Schema.optional(Schema.Boolean)
 });
-const MachineKey = Schema.Struct({
+const ApiKey = Schema.Struct({
 	keyId: Schema.String,
 	name: Schema.String,
 	enabled: Schema.Boolean,
@@ -203,27 +213,25 @@ const MachineKey = Schema.Struct({
 	expiresAt: Schema.NullOr(Timestamp),
 	createdAt: Timestamp
 });
-/** What every issuer action shares: any caller, and the contract's errors. */
-const anyone = {
-	caller: Action.Anyone,
-	error: errors
-};
-/** What every administration action shares: the owner as its caller, and the contract's errors. */
-const owned = {
-	caller: CurrentOwner,
-	error: errors
-};
+const anyone = { caller: Action.Anyone };
+const owned = { caller: CurrentOwner };
 const IssuerActions = [
 	Action.make("setupStatus", {
 		description: "Check whether the issuer needs its first owner account.",
 		readOnly: true,
 		...anyone,
+		error: [InternalServerError],
 		success: Schema.Struct({ required: Schema.Boolean })
 	}),
 	Action.make("setupOwner", {
 		description: "Create the first owner account.",
 		readOnly: false,
 		...anyone,
+		error: [
+			OwnerExists,
+			ProviderRefused,
+			InternalServerError
+		],
 		input: SetupInput,
 		success: Schema.Struct({ created: Schema.Boolean }).pipe(HttpApiSchema.status(201))
 	}),
@@ -231,6 +239,7 @@ const IssuerActions = [
 		description: "The signed list a resource server verifies API keys against: one sealed entry per key granted on the resource, readable only with that key.",
 		readOnly: true,
 		...anyone,
+		error: [InternalServerError],
 		input: Schema.Struct({ resource: Schema.String }),
 		success: Schema.Struct({ list: Schema.String })
 	})
@@ -248,12 +257,14 @@ const Administration = [
 		description: "List clients, resources, managed clients' resource access (what they may obtain), and every client's connections (what it holds).",
 		readOnly: true,
 		...owned,
+		error: [InternalServerError],
 		success: ClientListResult
 	}),
 	Action.make("createClient", {
 		description: "Register a first-party OAuth client. Returns its secret once when confidential.",
 		readOnly: false,
 		...owned,
+		error: [ProviderRefused, InternalServerError],
 		input: ClientInput,
 		success: ClientCredentials.pipe(HttpApiSchema.status(201))
 	}),
@@ -261,6 +272,12 @@ const Administration = [
 		description: "Rename a first-party client or change its redirect URIs and application type.",
 		readOnly: false,
 		...owned,
+		error: [
+			ClientNotFound,
+			ClientIsAutomatic,
+			ProviderRefused,
+			InternalServerError
+		],
 		input: ClientUpdateInput,
 		success: Client
 	}),
@@ -268,6 +285,7 @@ const Administration = [
 		description: "Delete a client and its stored authorization. An automatic client can register again; block it to keep it out.",
 		readOnly: false,
 		...owned,
+		error: [ClientNotFound, InternalServerError],
 		input: ClientId,
 		success: Schema.Struct({ deleted: Schema.Boolean })
 	}),
@@ -275,6 +293,7 @@ const Administration = [
 		description: "Revoke a client’s stored authorization, for one resource or all. It must authorize again; an automatic client asks for consent.",
 		readOnly: false,
 		...owned,
+		error: [ClientNotFound, InternalServerError],
 		input: ClientRevokeInput,
 		success: Schema.Struct({ revoked: Schema.Boolean })
 	}),
@@ -282,6 +301,7 @@ const Administration = [
 		description: "Block or unblock OAuth authorization for a client.",
 		readOnly: false,
 		...owned,
+		error: [ClientNotFound, InternalServerError],
 		input: ClientBlockInput,
 		success: Schema.Struct({ blocked: Schema.Boolean })
 	}),
@@ -289,6 +309,12 @@ const Administration = [
 		description: "Rotate a confidential client secret. Returns the new secret once.",
 		readOnly: false,
 		...owned,
+		error: [
+			ClientNotFound,
+			ClientIsAutomatic,
+			ProviderRefused,
+			InternalServerError
+		],
 		input: ClientId,
 		success: ClientCredentials
 	}),
@@ -296,6 +322,11 @@ const Administration = [
 		description: "Set the resources a managed client may obtain. Removing one revokes its authorization for it. Automatic clients may ask for any resource with consent.",
 		readOnly: false,
 		...owned,
+		error: [
+			ClientNotFound,
+			ClientIsAutomatic,
+			InternalServerError
+		],
 		input: ClientAccessInput,
 		success: ClientAccessResult
 	}),
@@ -303,6 +334,7 @@ const Administration = [
 		description: "Create an OAuth resource and its scopes.",
 		readOnly: false,
 		...owned,
+		error: [ProviderRefused, InternalServerError],
 		input: ResourceInput,
 		success: Resource.pipe(HttpApiSchema.status(201))
 	}),
@@ -310,6 +342,11 @@ const Administration = [
 		description: "Update an OAuth resource and its scopes.",
 		readOnly: false,
 		...owned,
+		error: [
+			ResourceNotFound,
+			ProviderRefused,
+			InternalServerError
+		],
 		input: ResourceInput,
 		success: Resource
 	}),
@@ -317,6 +354,7 @@ const Administration = [
 		description: "Delete a resource, its client access and every client’s authorization for it. API-key permissions are retained; recreating the resource restores them.",
 		readOnly: false,
 		...owned,
+		error: [ResourceNotFound, InternalServerError],
 		input: ResourceId,
 		success: Schema.Struct({ deleted: Schema.Boolean })
 	}),
@@ -324,48 +362,52 @@ const Administration = [
 		description: "List API key metadata without secret values.",
 		readOnly: true,
 		...owned,
-		success: Schema.Struct({ keys: Schema.Array(MachineKey) })
+		error: [InternalServerError],
+		success: Schema.Struct({ keys: Schema.Array(ApiKey) })
 	}),
 	Action.make("createApiKey", {
 		description: "Create a scoped API key. Returns its secret once.",
 		readOnly: false,
 		...owned,
+		error: [ProviderRefused, InternalServerError],
 		input: ApiKeyInput,
-		success: MachineKey.pipe(Schema.fieldsAssign({ key: Schema.String }), HttpApiSchema.status(201))
+		success: ApiKey.pipe(Schema.fieldsAssign({ key: Schema.String }), HttpApiSchema.status(201))
 	}),
 	Action.make("updateApiKey", {
 		description: "Update an API key’s name, permissions or enabled state.",
 		readOnly: false,
 		...owned,
+		error: [
+			ApiKeyNotFound,
+			ProviderRefused,
+			InternalServerError
+		],
 		input: ApiKeyUpdate,
-		success: MachineKey
+		success: ApiKey
 	}),
 	Action.make("deleteApiKey", {
 		description: "Delete an API key.",
 		readOnly: false,
 		...owned,
+		error: [ApiKeyNotFound, InternalServerError],
 		input: ApiKeyId,
 		success: Schema.Struct({ deleted: Schema.Boolean })
 	})
 ];
-/**
-* Every action over HTTP, at `/api/<action>`, owner administration authenticated by
-* `authentication`: the server's, from its deployment's cookie, or the browser's
-* `OwnerSession`. Resource servers read `/api/keyList`, so that path is part of the protocol.
-*/
+[.../* @__PURE__ */ new Set([
+	...[...IssuerActions, ...Administration].flatMap((action) => action.error),
+	...undecided,
+	UnreadableRequest
+])];
 const binding = (authentication) => ActionHttp.make([...Administration, ...IssuerActions], { authentication });
 binding(OwnerSession);
-/**
-* Owner administration over HTTP for a client holding an access token, such as the CLI, at
-* `/api/owner/<action>`: the actions `/mcp` serves, authenticated as it is, by `OwnerToken`.
-*/
 const OwnerHttp = ActionHttp.make(Administration, {
 	prefix: "/api/owner",
 	authentication: OwnerToken
 });
 //#endregion
 //#region package.json
-var version = "0.22.0";
+var version = "0.23.0";
 //#endregion
 //#region src/credentials.ts
 /** The kept sign-ins cannot be read or written. */
@@ -402,17 +444,8 @@ const Credentials = Schema.Struct({
 	signIns: Schema.Array(SignIn)
 });
 const CredentialsJson = Schema.fromJsonString(Credentials);
-/** Where the sign-ins are kept: `$XDG_CONFIG_HOME/clankerauth`, or `~/.config/clankerauth`. */
 const credentialsPath = () => join(process.env["XDG_CONFIG_HOME"] || join(homedir(), ".config"), "clankerauth", "credentials.json");
-/**
-* The sign-ins, if there are any. A file this version cannot decode, such as one another
-* version wrote, holds none: the next `login` replaces it.
-*/
 const readCredentials = () => Effect.tryPromise(() => readFile(credentialsPath(), "utf8")).pipe(Effect.map(Schema.decodeOption(CredentialsJson)), Effect.catchIf((error) => error.cause instanceof Error && "code" in error.cause && error.cause.code === "ENOENT", () => Effect.succeedNone), Effect.mapError(failed("Cannot read")));
-/**
-* Replace the sign-ins, readable by their owner alone. Written beside the file and renamed
-* over it, so a command interrupted mid-write never leaves a refresh token half-saved.
-*/
 const writeCredentials = Effect.fn("Credentials.write")(function* (credentials) {
 	const path = credentialsPath();
 	const json = yield* Schema.encodeEffect(CredentialsJson)(credentials);
@@ -426,10 +459,6 @@ const writeCredentials = Effect.fn("Credentials.write")(function* (credentials)
 		await rename(staging, path);
 	}).pipe(Effect.tapError(() => Effect.promise(() => rm(staging, { force: true }))));
 }, Effect.mapError(failed("Cannot write")));
-/**
-* Keep `signIn` in place of the one for its resource. The file is read again first, so a
-* command refreshing another resource meanwhile keeps its rotated refresh token too.
-*/
 const saveSignIn = Effect.fn("Credentials.saveSignIn")(function* (issuer, signIn) {
 	const current = Option.filter(yield* readCredentials(), ({ url }) => url === issuer.url);
 	const base = Option.getOrElse(current, () => issuer);
@@ -451,20 +480,13 @@ const Server = Schema.Struct({
 	registration_endpoint: Schema.String,
 	revocation_endpoint: Schema.String
 });
-/** This CLI as the issuer knows it: a public client, authenticating with nothing. */
 const client = (clientId) => ({ client_id: clientId });
-/** Plain HTTP is allowed for an issuer the owner named over it, such as one on loopback. */
 const transport = (url) => ({ [oauth.allowInsecureRequests]: new URL(url).protocol === "http:" });
 /** The RFC 9728 check's failure: the metadata names another resource than the one asked for. */
 const NamedElsewhere = Schema.Struct({
 	attribute: Schema.Literal("resource"),
 	body: Schema.Struct({ resource: Schema.String })
 });
-/**
-* What went wrong: what the issuer said when it sent an OAuth error, where it is when it
-* names another address than the one asked, the status of an answer the library refused,
-* or why a request failed.
-*/
 const reason = (error) => {
 	if (error instanceof oauth.ResponseBodyError || error instanceof oauth.AuthorizationResponseError) return [error.error, error.error_description].filter(Boolean).join(": ");
 	if (error instanceof oauth.OperationProcessingError) {
@@ -474,16 +496,10 @@ const reason = (error) => {
 	}
 	return error.cause instanceof Error ? `${error.message} (${error.cause.message})` : error.message;
 };
-/** Run one step of the protocol, failing with what the issuer, or the library, said. */
 const step = (what, run) => Effect.tryPromise({
 	try: run,
 	catch: (error) => new OAuthError({ message: `${what}: ${error instanceof Error ? reason(error) : String(error)}` })
 });
-/**
-* The issuer at `url`, its origin: administration's RFC 9728 metadata at the origin root,
-* which must name that root, and the RFC 8414 metadata of the issuer it names, which must
-* name that issuer. Both checks are the library's.
-*/
 const discover = Effect.fn("OAuth.discover")(function* (url) {
 	const administration = new URL("/", url);
 	const [named] = (yield* step(`Discovery at ${administration.origin}`, async () => oauth.processResourceDiscoveryResponse(administration, await oauth.resourceDiscoveryRequest(administration, transport(url))))).authorization_servers ?? [];
@@ -495,10 +511,6 @@ const discover = Effect.fn("OAuth.discover")(function* (url) {
 	})));
 	return yield* Schema.decodeUnknownEffect(Server)(server).pipe(Effect.mapError((error) => new OAuthError({ message: `Discovery: the issuer lacks an endpoint (${error.message})` })));
 });
-/**
-* Register this CLI as a public native client. The issuer matches a loopback redirect without
-* its port (RFC 8252), so one registration serves every port a sign-in listens on.
-*/
 const register = (url, server, redirectUri) => step("Registration", async () => oauth.processDynamicClientRegistrationResponse(await oauth.dynamicClientRegistrationRequest(server, {
 	client_name: "clankerauth CLI",
 	redirect_uris: [redirectUri],
@@ -507,10 +519,26 @@ const register = (url, server, redirectUri) => step("Registration", async () =>
 	grant_types: ["authorization_code", "refresh_token"],
 	response_types: ["code"]
 }, transport(url)))).pipe(Effect.map((registered) => registered.client_id));
-/**
-* Check the redirect a browser brought back (its state, the RFC 9207 issuer, an error the
-* issuer sent instead of a code) and exchange its code for tokens.
-*/
+const authorizationRequest = Effect.fn("OAuth.authorizationRequest")(function* (server, clientId, redirectUri, scope, resource) {
+	const verifier = oauth.generateRandomCodeVerifier();
+	const state = oauth.generateRandomState();
+	const url = new URL(server.authorization_endpoint);
+	url.search = new URLSearchParams({
+		client_id: clientId,
+		redirect_uri: redirectUri,
+		response_type: "code",
+		scope,
+		resource,
+		code_challenge: yield* Effect.promise(() => oauth.calculatePKCECodeChallenge(verifier)),
+		code_challenge_method: "S256",
+		state
+	}).toString();
+	return {
+		url,
+		state,
+		verifier
+	};
+});
 const exchangeCode = (url, server, clientId, callback, expected, resource) => step("Sign-in", async () => {
 	const parameters = oauth.validateAuthResponse(server, client(clientId), callback, expected.state);
 	return oauth.processAuthorizationCodeResponse(server, client(clientId), await oauth.authorizationCodeGrantRequest(server, client(clientId), oauth.None(), parameters, expected.redirectUri, expected.verifier, {
@@ -518,45 +546,27 @@ const exchangeCode = (url, server, clientId, callback, expected, resource) => st
 		...transport(url)
 	}));
 });
-/** Refresh the tokens of one sign-in: the refresh token rotates. */
 const refresh = (credentials, refreshToken, resource) => step("Refresh", async () => oauth.processRefreshTokenResponse(credentials.server, client(credentials.clientId), await oauth.refreshTokenGrantRequest(credentials.server, client(credentials.clientId), oauth.None(), refreshToken, {
 	additionalParameters: { resource },
 	...transport(credentials.url)
 })));
-/** Revoke a refresh token, and with it every token of its family. */
 const revoke = (credentials, refreshToken) => step("Revocation", async () => oauth.processRevocationResponse(await oauth.revocationRequest(credentials.server, client(credentials.clientId), oauth.None(), refreshToken, {
 	additionalParameters: { token_type_hint: "refresh_token" },
 	...transport(credentials.url)
 })));
 //#endregion
 //#region src/login.ts
-/** The issuer's own resource, administration: its origin root, as discovery checks. */
-const administrationOf = (url) => new URL("/", url).href;
-/** The scopes a sign-in to administration asks for unless told otherwise. */
-const administrationScopes = "clankerauth:read clankerauth:write";
-/** A sign-in asks for a refresh token too, so it lasts while it is used. */
+const administrationScope = `${administrationScopes.read} ${administrationScopes.write}`;
 const withRefresh = (scope) => scope.split(" ").includes("offline_access") ? scope : `${scope} offline_access`;
-/**
-* The command that signs in to `resource` again: administration needs neither flag unless
-* it was granted other scopes than its default, and another resource needs both.
-*/
 const loginHint = (url, resource, scope) => {
 	const asked = scope?.split(" ").filter((granted) => granted !== "offline_access").join(" ");
-	const administration = resource === administrationOf(url);
-	return `clankerauth login ${url}${administration ? "" : ` --resource ${resource}`}${administration && (asked === void 0 || asked === "clankerauth:read clankerauth:write") ? "" : ` --scope "${asked ?? "<scopes>"}"`}`;
+	const administration = resource === administrationIdentifier(url);
+	return `clankerauth login ${url}${administration ? "" : ` --resource ${resource}`}${administration && (asked === void 0 || asked === administrationScope) ? "" : ` --scope "${asked ?? "<scopes>"}"`}`;
 };
-/** The redirect a registration names; a sign-in adds the port it listens on. */
 const registeredRedirect = "http://127.0.0.1/callback";
-/** How long a sign-in waits for the owner to approve it in the browser. */
 const approvalWindow = "5 minutes";
-/** When tokens issued now expire; an issuer that does not say is asked again next time. */
 const expiry = (tokens) => new Date(Date.now() + (tokens.expires_in ?? 0) * 1e3).toISOString();
-/**
-* The callback page says nothing of the outcome, which is decided after the browser has
-* its answer: the terminal reports it.
-*/
 const page = "<!doctype html><meta charset=\"utf-8\"><title>clankerauth</title><p>Return to the terminal.</p>";
-/** Listen on a free loopback port for the one request the authorization redirect makes. */
 const listen = Effect.acquireRelease(Effect.gen(function* () {
 	const received = yield* Deferred.make();
 	const server = createServer((request, response) => {
@@ -580,21 +590,14 @@ const listen = Effect.acquireRelease(Effect.gen(function* () {
 	server.closeAllConnections();
 	server.close();
 }));
-/** Revoke these sign-ins' refresh tokens, as far as the issuer can be reached. */
 const revokeAll = (credentials, signIns) => Effect.forEach(signIns, ({ refreshToken }) => Effect.ignore(revoke(credentials, refreshToken)), {
 	concurrency: "unbounded",
 	discard: true
 });
-/**
-* Sign in to the issuer at `url` as its owner, for `resource`, administration when none:
-* discover the issuer, register this CLI once per issuer, have the owner approve the URL
-* printed on stderr, and keep the tokens beside the sign-ins to other resources. Signing
-* in to another issuer than the kept one revokes and forgets the kept one's sign-ins.
-*/
 const login = Effect.fn("Cli.login")(function* (url, target, asked) {
 	const origin = new URL(url).origin;
 	const server = yield* discover(origin);
-	const resource = Option.getOrElse(target, () => administrationOf(origin));
+	const resource = Option.getOrElse(target, () => administrationIdentifier(origin));
 	const kept = yield* readCredentials();
 	const previous = Option.filter(kept, (credentials) => credentials.url === origin);
 	const clientId = yield* Option.match(previous, {
@@ -603,20 +606,8 @@ const login = Effect.fn("Cli.login")(function* (url, target, asked) {
 	});
 	const { port, received } = yield* listen;
 	const redirectUri = `http://127.0.0.1:${port}/callback`;
-	const verifier = oauth.generateRandomCodeVerifier();
-	const state = oauth.generateRandomState();
 	const scope = withRefresh(asked);
-	const authorization = new URL(server.authorization_endpoint);
-	authorization.search = new URLSearchParams({
-		client_id: clientId,
-		redirect_uri: redirectUri,
-		response_type: "code",
-		scope,
-		resource,
-		code_challenge: yield* Effect.promise(() => oauth.calculatePKCECodeChallenge(verifier)),
-		code_challenge_method: "S256",
-		state
-	}).toString();
+	const { url: authorization, state, verifier } = yield* authorizationRequest(server, clientId, redirectUri, scope, resource);
 	yield* Effect.sync(() => process.stderr.write(`Open this URL in your browser to approve the sign-in:\n\n  ${authorization.href}\n\n`));
 	const callback = yield* Deferred.await(received).pipe(Effect.timeoutOrElse({
 		duration: approvalWindow,
@@ -655,10 +646,6 @@ const login = Effect.fn("Cli.login")(function* (url, target, asked) {
 		scope: signIn.scope
 	};
 }, Effect.scoped);
-/**
-* A current access token for `resource`, refreshed first when it has expired or is about
-* to: the refresh token rotates, so the new pair is saved before the token is used.
-*/
 const accessToken = Effect.fn("Cli.accessToken")(function* (credentials, resource) {
 	const signIn = credentials.signIns.find((held) => held.resource === resource);
 	if (signIn === void 0) return yield* new OAuthError({ message: `Not signed in to ${resource}: run \`${loginHint(credentials.url, resource)}\` first.` });
@@ -674,11 +661,6 @@ const accessToken = Effect.fn("Cli.accessToken")(function* (credentials, resourc
 	yield* saveSignIn(credentials, refreshed);
 	return refreshed.accessToken;
 });
-/**
-* Forget the sign-in to `resource`, or every one when none is named, revoking each refresh
-* token first when the issuer can be reached. The file goes with the last sign-in, and
-* with a file no sign-in can be read from.
-*/
 const logout = Effect.fn("Cli.logout")(function* (resource) {
 	const stored = yield* readCredentials();
 	if (Option.isNone(stored)) {
@@ -700,18 +682,15 @@ const logout = Effect.fn("Cli.logout")(function* (resource) {
 });
 //#endregion
 //#region src/main.ts
-/** A failure of this CLI's own, rendered as its message on stderr, exiting 1. */
 const refused = (error) => new CliError.UserError({
 	cause: error,
 	userMessage: error.message
 });
 const json = (value) => Console.log(JSON.stringify(value, null, 2));
-/** A resource identifier as the issuer keeps it: canonical, `https://notes.example/`. */
 const resourceFlag = (description) => Flag.String("resource").pipe(Flag.withDescription(description), Flag.mapTryCatch((resource) => new URL(resource).href, () => "--resource must be a URL, such as https://notes.example/"), Flag.optional);
-/** The scopes a sign-in asks for: `--scope`, which another resource than administration needs. */
 const scopeFor = Effect.fn("Cli.scopeFor")(function* (resource, scope) {
 	if (Option.isSome(scope)) return scope.value;
-	if (Option.isNone(resource)) return administrationScopes;
+	if (Option.isNone(resource)) return administrationScope;
 	const message = `Name the scopes to ask ${resource.value} for with --scope.`;
 	return yield* new CliError.UserError({
 		cause: message,
@@ -721,10 +700,9 @@ const scopeFor = Effect.fn("Cli.scopeFor")(function* (resource, scope) {
 const loginCommand = Command.make("login", {
 	url: Argument.String("url").pipe(Argument.withDescription("The issuer's origin, its CLANKERAUTH_BASE_URL")),
 	resource: resourceFlag("Sign in to this resource instead of administration, for `token` to use"),
-	scope: Flag.String("scope").pipe(Flag.withDescription(`The scopes to ask for, space-separated: needed with --resource, and "${administrationScopes}" for administration by default`), Flag.optional)
+	scope: Flag.String("scope").pipe(Flag.withDescription(`The scopes to ask for, space-separated: needed with --resource, and "${administrationScope}" for administration by default`), Flag.optional)
 }, ({ url, resource, scope }) => scopeFor(resource, scope).pipe(Effect.flatMap((asked) => login(url, resource, asked).pipe(Effect.mapError(refused))), Effect.flatMap(json))).pipe(Command.withDescription("Sign in to an issuer as its owner, for administration or, with --resource, for another resource: approve the URL it prints in the browser. Sign-ins are kept in ~/.config/clankerauth."));
 const logoutCommand = Command.make("logout", { resource: resourceFlag("Sign out of this resource alone") }, ({ resource }) => logout(resource).pipe(Effect.mapError(refused), Effect.flatMap(json))).pipe(Command.withDescription("Revoke the sign-ins, or the one to --resource, and forget them."));
-/** The kept sign-ins, or how to make one. */
 const signedIn = Effect.gen(function* () {
 	const stored = yield* readCredentials().pipe(Effect.mapError(refused));
 	if (Option.isNone(stored)) return yield* new CliError.UserError({
@@ -733,22 +711,16 @@ const signedIn = Effect.gen(function* () {
 	});
 	return stored.value;
 });
-/** Prints the token alone, so a script takes the whole output as it. */
 const tokenCommand = Command.make("token", { resource: resourceFlag("The resource whose token to print; administration by default") }, ({ resource }) => Effect.gen(function* () {
 	const credentials = yield* signedIn;
-	const token = yield* accessToken(credentials, Option.getOrElse(resource, () => administrationOf(credentials.url))).pipe(Effect.mapError(refused));
+	const token = yield* accessToken(credentials, Option.getOrElse(resource, () => administrationIdentifier(credentials.url))).pipe(Effect.mapError(refused));
 	yield* Effect.sync(() => process.stdout.write(`${token}\n`));
 })).pipe(Command.withDescription("Print a current access token for a resource signed in to, refreshing it first when it has expired."));
-/**
-* The client every administration command calls through: the signed-in issuer's origin and
-* a current administration access token, refreshed and saved first when it has expired.
-*/
 const administrationClient = Effect.gen(function* () {
 	const credentials = yield* signedIn;
-	const token = yield* accessToken(credentials, administrationOf(credentials.url)).pipe(Effect.mapError(refused));
+	const token = yield* accessToken(credentials, administrationIdentifier(credentials.url)).pipe(Effect.mapError(refused));
 	return HttpClient.mapRequest(yield* HttpClient.HttpClient, (request) => request.pipe(HttpClientRequest.prependUrl(credentials.url), HttpClientRequest.bearerToken(token)));
 });
-/** Every administration action, as a command of its own, called over `/api/owner`. */
 const administration = Administration.map((action) => ActionCli.remoteCommand(OwnerHttp, action).pipe(Command.provideEffect(HttpClient.HttpClient, administrationClient)));
 const cli = Command.make("clankerauth").pipe(Command.withDescription("Administer a clankerauth issuer as its owner, and hand other commands its tokens. Results are JSON on stdout; a created key or client secret is in it once."), Command.withSubcommands([
 	loginCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "The clankerauth command line: sign in to an issuer as its owner and administer it over HTTP.",
   "license": "MIT",
   "repository": {
@@ -21,17 +21,17 @@
   "dependencies": {
     "@effect/platform-node": "4.0.4",
     "@effect/platform-node-shared": "4.0.4",
-    "@gjermundgaraba/effect-actions": "0.16.0",
+    "@gjermundgaraba/effect-actions": "0.17.0",
     "effect": "4.0.4",
     "oauth4webapi": "3.8.8"
   },
   "devDependencies": {
     "@clankerauth/admin-api": "0.1.0",
-    "@gjermundgaraba/clankerauth-dev": "0.22.0",
+    "@gjermundgaraba/clankerauth-dev": "0.23.0",
     "@types/node": "26.6.4",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vite-plus": "1.1.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.2.0",
+    "vite-plus": "1.2.0"
   },
   "engines": {
     "node": ">=26"