@gjermundgaraba/clankerauth 0.23.1 → 0.25.0

package/README.md

@@ -1,6 +1,6 @@
 # @gjermundgaraba/clankerauth
 
-The `clankerauth` command: sign in to a [clankerauth](https://github.com/gjermundgaraba/clankerauth) issuer as its owner, run every administration action over HTTP, and hand other commands access tokens for the issuer's resources. It needs Node 26 or newer and an issuer at 0.16.0 or later.
+The `clankerauth` command: sign in to a [clankerauth](https://github.com/gjermundgaraba/clankerauth) issuer as its owner, run every administration action over HTTP, and hand other commands access tokens for the issuer's resources. It needs Node 26 or newer and an issuer at 0.24.0 or later.
 
 ```sh
 npm install --global @gjermundgaraba/clankerauth
@@ -12,22 +12,23 @@ clankerauth create-api-key --name "notes sync" \
 clankerauth logout
 ```
 
-`login` discovers the issuer at the URL given, which must be its own origin, `CLANKERAUTH_BASE_URL`; registers the command as a native OAuth client the first time; prints the approval URL on stderr for the owner to open; and listens for the redirect on a loopback port. It asks for `clankerauth:read clankerauth:write`, unless `--scope` names fewer: `--scope clankerauth:read` lists and never changes. The sign-ins are kept in `$XDG_CONFIG_HOME/clankerauth/credentials.json`, `~/.config/clankerauth/credentials.json` by default, readable by their owner alone; a file the command cannot read, such as one another version wrote, counts as signed out and the next `login` replaces it. A command refreshes an access token once it has expired and saves the rotated refresh token, so a sign-in lasts while it is used at least every 30 days. `logout` revokes every sign-in and deletes the file.
+`login <url>` signs in to the resource `url` identifies, reading it from its `/.well-known/oauth-protected-resource`: the issuer's own origin, `CLANKERAUTH_BASE_URL`, publishes administration, and an application's URL publishes its resource. It then discovers the issuer that resource names; registers the command there as a native OAuth client, a new one for each sign-in; opens the approval page in the browser and prints its URL on stderr, for a terminal with no browser to open, or alone with `--no-browser`; and listens for the redirect on a loopback port. It asks for every scope the resource publishes, `clankerauth:read clankerauth:write` for administration, unless `--scope` names fewer: `--scope clankerauth:read` lists and never changes. Beside them it asks for `offline_access`, alone for a resource that publishes no scopes. A resource must publish that document, and so be identified by an `http:` or `https:` URL, to be signed in to.
+
+The sign-ins are kept in `$XDG_CONFIG_HOME/clankerauth/sign-ins.json`, `~/.config/clankerauth/sign-ins.json` by default, readable by their owner alone: one per resource, each with its own issuer, so signing in at a second issuer leaves the first's alone. A file the command cannot read, such as one another version wrote, counts as signed out and the next `login` replaces it. A `login` to a resource already signed in to replaces that sign-in and revokes it. A command refreshes an access token as it is about to expire and saves the rotated refresh token, so a sign-in lasts while it is used at least every 30 days; when the issuer refuses a refresh, the error names the `login` that asks for the same scopes again. Every change to the file holds its lock, so commands and programs running at once refresh an expired sign-in once, and `logout` revokes the refresh token that is current. `logout` revokes every sign-in and deletes the file, and `logout <url>` the one whose resource that URL is under alone.
+
+Administration commands act at the issuer of the one administration sign-in kept. Signed in to administration at several issuers, name one with `CLANKERAUTH_URL`, its origin; a value that is no URL is refused.
 
 ## Tokens for other commands
 
-`login --resource <identifier> --scope <scopes>` signs in to one of the issuer's resources instead of administration, with its own consent and refresh token, kept beside the others. `token --resource <identifier>` prints a current access token for it, and nothing else, refreshing it first when it has expired; without `--resource` it prints administration's. Another command, or a script, gets its bearer token from there instead of keeping a key:
+`token <url>` prints a current access token for the resource signed in to that the URL is under, the most specific when several are, and nothing else, refreshing it first when it is about to expire; without a URL it prints administration's. Another command, or a script, gets its bearer token from there instead of keeping a key; a program written with Effect uses `token` of [`@gjermundgaraba/clankerauth-sdk/credentials`](../../packages/sdk/README.md) instead, which reads and refreshes the same sign-in:
 
 ```sh
-clankerauth login https://clankerauth.home.example \
-  --resource https://notes.home.example/ --scope "notes:read notes:write"
-curl -H "authorization: Bearer $(clankerauth token --resource https://notes.home.example/)" \
+clankerauth login https://notes.home.example
+curl -H "authorization: Bearer $(clankerauth token https://notes.home.example/api/list-notes)" \
   https://notes.home.example/api/list-notes
-clankerauth logout --resource https://notes.home.example/
+clankerauth logout https://notes.home.example
 ```
 
-The identifier is the resource's, exactly as the dashboard lists it. The file holds one issuer's sign-ins: signing in to another issuer revokes and forgets the kept ones first.
-
 Every other command is an administration action, named after it in kebab case, with a flag per input field: `clankerauth <command> --help` lists them. A field that is not text takes JSON, such as `--permissions` above or `--expires-at null`. A command prints the action's result as JSON on stdout, and a refusal on stderr, exiting 1. A created API key or client secret is in that JSON once, so send it where it belongs:
 
 ```sh

package/dist/main.mjs

@@ -1,19 +1,15 @@
 #!/usr/bin/env node
-import { Console, Context, Deferred, Effect, Option, Schema } from "effect";
+import { spawn } from "node:child_process";
+import { Config, Console, Context, Effect, Option, Redacted, Schema } from "effect";
 import { Argument, CliError, Command, Flag } from "effect/cli";
-import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
+import { FetchHttpClient, HttpClient } from "effect/http";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Credentials from "@gjermundgaraba/clankerauth-sdk/credentials";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 import { HttpApiSchema, HttpApiSecurity } from "effect/http-api";
-import { randomBytes } from "node:crypto";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { createServer } from "node:http";
-import * as oauth from "oauth4webapi";
 //#region ../../packages/admin-api/dist/index.js
 /**
 * This issuer's own fault: a failed query, an unreadable row, an unexpected provider failure.
@@ -89,10 +85,6 @@ const ownerSession = (cookie) => Authentication.make("clankerauth.OwnerSession",
 const OwnerSession = ownerSession("better-auth.session_token");
 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.check(Schema.isPattern(/\S/u, { message: "Setup requires an email" })),
@@ -161,6 +153,11 @@ const ResourceInput = Schema.Struct({
 	scopes: Schema.Array(Schema.String.check(Schema.isPattern(/^\s*[\x21\x23-\x5B\x5D-\x7E]+\s*$/u, { message: "Resources require well-formed custom scopes" })))
 });
 const ResourceId = Schema.Struct({ identifier: Schema.String });
+/** What `putResource` stored, and whether it created the resource rather than updating it. */
+const PutResourceResult = Schema.Struct({
+	resource: Resource,
+	created: Schema.Boolean
+});
 const ClientAccess = Schema.Struct({
 	client_id: Schema.String,
 	resource: Schema.String
@@ -330,25 +327,21 @@ const Administration = [
 		input: ClientAccessInput,
 		success: ClientAccessResult
 	}),
-	Action.make("createResource", {
-		description: "Create an OAuth resource and its scopes.",
-		readOnly: false,
+	Action.make("getResource", {
+		description: "Get one resource and its scopes by identifier.",
+		readOnly: true,
 		...owned,
-		error: [ProviderRefused, InternalServerError],
-		input: ResourceInput,
-		success: Resource.pipe(HttpApiSchema.status(201))
+		error: [ResourceNotFound, InternalServerError],
+		input: ResourceId,
+		success: ResourceSummary
 	}),
-	Action.make("updateResource", {
-		description: "Update an OAuth resource and its scopes.",
+	Action.make("putResource", {
+		description: "Create an OAuth resource, or update the one with its identifier, to exactly these name and scopes.",
 		readOnly: false,
 		...owned,
-		error: [
-			ResourceNotFound,
-			ProviderRefused,
-			InternalServerError
-		],
+		error: [ProviderRefused, InternalServerError],
 		input: ResourceInput,
-		success: Resource
+		success: PutResourceResult
 	}),
 	Action.make("deleteResource", {
 		description: "Delete a resource, its client access and every client’s authorization for it. API-key permissions are retained; recreating the resource restores them.",
@@ -407,279 +400,7 @@ const OwnerHttp = ActionHttp.make(Administration, {
 });
 //#endregion
 //#region package.json
-var version = "0.23.1";
-//#endregion
-//#region src/credentials.ts
-/** The kept sign-ins cannot be read or written. */
-var CredentialsError = class extends Schema.TaggedError()("CredentialsError", { message: Schema.String }) {};
-const failed = (what) => (error) => new CredentialsError({ message: `${what} ${credentialsPath()}: ${error.message}` });
-/**
-* The owner's authorization for one resource: administration or an application's. The
-* access token lasts fifteen minutes and the refresh token rotates on every use, so the
-* file is rewritten whenever a command refreshes.
-*/
-const SignIn = Schema.Struct({
-	/** The token audience: a resource identifier, such as `https://notes.home.example/`. */
-	resource: Schema.String,
-	scope: Schema.String,
-	accessToken: Schema.String,
-	refreshToken: Schema.String,
-	/** When the access token expires, as an ISO instant. */
-	expiresAt: Schema.String
-});
-/**
-* The issuer signed in to, the client this CLI registered there, and one sign-in per
-* resource. `server` is the part of the issuer's RFC 8414 metadata a refresh and a
-* revocation need, under its RFC names.
-*/
-const Credentials = Schema.Struct({
-	/** The issuer's origin, `CLANKERAUTH_BASE_URL`: where `/api/owner/<action>` is served. */
-	url: Schema.String,
-	server: Schema.Struct({
-		issuer: Schema.String,
-		token_endpoint: Schema.String,
-		revocation_endpoint: Schema.String
-	}),
-	clientId: Schema.String,
-	signIns: Schema.Array(SignIn)
-});
-const CredentialsJson = Schema.fromJsonString(Credentials);
-const credentialsPath = () => join(process.env["XDG_CONFIG_HOME"] || join(homedir(), ".config"), "clankerauth", "credentials.json");
-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")));
-const writeCredentials = Effect.fn("Credentials.write")(function* (credentials) {
-	const path = credentialsPath();
-	const json = yield* Schema.encodeEffect(CredentialsJson)(credentials);
-	const staging = `${path}.${randomBytes(6).toString("hex")}`;
-	yield* Effect.tryPromise(async () => {
-		await mkdir(dirname(path), {
-			recursive: true,
-			mode: 448
-		});
-		await writeFile(staging, `${json}\n`, { mode: 384 });
-		await rename(staging, path);
-	}).pipe(Effect.tapError(() => Effect.promise(() => rm(staging, { force: true }))));
-}, Effect.mapError(failed("Cannot write")));
-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);
-	yield* writeCredentials({
-		...base,
-		signIns: [...base.signIns.filter(({ resource }) => resource !== signIn.resource), signIn]
-	});
-});
-const removeCredentials = () => Effect.tryPromise(() => rm(credentialsPath(), { force: true })).pipe(Effect.mapError(failed("Cannot remove")));
-//#endregion
-//#region src/oauth.ts
-/** Something the issuer answered that a sign-in, a refresh or a revocation cannot go on from. */
-var OAuthError = class extends Schema.TaggedError()("OAuthError", { message: Schema.String }) {};
-/** The issuer's RFC 8414 metadata a sign-in uses, every endpoint required. */
-const Server = Schema.Struct({
-	issuer: Schema.String,
-	authorization_endpoint: Schema.String,
-	token_endpoint: Schema.String,
-	registration_endpoint: Schema.String,
-	revocation_endpoint: Schema.String
-});
-const client = (clientId) => ({ client_id: clientId });
-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 })
-});
-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) {
-		const named = Schema.decodeUnknownOption(NamedElsewhere)(error.cause);
-		if (Option.isSome(named)) return `the issuer is at ${new URL(named.value.body.resource).origin}, its CLANKERAUTH_BASE_URL: sign in there`;
-		if (error.cause instanceof Response) return `${error.message} (HTTP ${error.cause.status})`;
-	}
-	return error.cause instanceof Error ? `${error.message} (${error.cause.message})` : error.message;
-};
-const step = (what, run) => Effect.tryPromise({
-	try: run,
-	catch: (error) => new OAuthError({ message: `${what}: ${error instanceof Error ? reason(error) : String(error)}` })
-});
-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 ?? [];
-	if (named === void 0) return yield* new OAuthError({ message: "Discovery: the issuer names no authorization server" });
-	const issuer = new URL(named);
-	const server = yield* step("Discovery", async () => oauth.processDiscoveryResponse(issuer, await oauth.discoveryRequest(issuer, {
-		algorithm: "oauth2",
-		...transport(url)
-	})));
-	return yield* Schema.decodeUnknownEffect(Server)(server).pipe(Effect.mapError((error) => new OAuthError({ message: `Discovery: the issuer lacks an endpoint (${error.message})` })));
-});
-const register = (url, server, redirectUri) => step("Registration", async () => oauth.processDynamicClientRegistrationResponse(await oauth.dynamicClientRegistrationRequest(server, {
-	client_name: "clankerauth CLI",
-	redirect_uris: [redirectUri],
-	application_type: "native",
-	token_endpoint_auth_method: "none",
-	grant_types: ["authorization_code", "refresh_token"],
-	response_types: ["code"]
-}, transport(url)))).pipe(Effect.map((registered) => registered.client_id));
-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, {
-		additionalParameters: { resource },
-		...transport(url)
-	}));
-});
-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)
-})));
-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
-const administrationScope = `${administrationScopes.read} ${administrationScopes.write}`;
-const withRefresh = (scope) => scope.split(" ").includes("offline_access") ? scope : `${scope} offline_access`;
-const loginHint = (url, resource, scope) => {
-	const asked = scope?.split(" ").filter((granted) => granted !== "offline_access").join(" ");
-	const administration = resource === administrationIdentifier(url);
-	return `clankerauth login ${url}${administration ? "" : ` --resource ${resource}`}${administration && (asked === void 0 || asked === administrationScope) ? "" : ` --scope "${asked ?? "<scopes>"}"`}`;
-};
-const registeredRedirect = "http://127.0.0.1/callback";
-const approvalWindow = "5 minutes";
-const expiry = (tokens) => new Date(Date.now() + (tokens.expires_in ?? 0) * 1e3).toISOString();
-const page = "<!doctype html><meta charset=\"utf-8\"><title>clankerauth</title><p>Return to the terminal.</p>";
-const listen = Effect.acquireRelease(Effect.gen(function* () {
-	const received = yield* Deferred.make();
-	const server = createServer((request, response) => {
-		const url = new URL(request.url ?? "/", "http://127.0.0.1");
-		if (url.pathname !== "/callback") {
-			response.writeHead(404).end();
-			return;
-		}
-		response.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page);
-		Deferred.doneUnsafe(received, Effect.succeed(url.searchParams));
-	});
-	return {
-		server,
-		port: yield* Effect.callback((resume) => {
-			server.once("error", (error) => resume(Effect.fail(new OAuthError({ message: `Cannot listen for the redirect: ${error.message}` }))));
-			server.listen(0, "127.0.0.1", () => resume(Effect.succeed(server.address().port)));
-		}),
-		received
-	};
-}), ({ server }) => Effect.sync(() => {
-	server.closeAllConnections();
-	server.close();
-}));
-const revokeAll = (credentials, signIns) => Effect.forEach(signIns, ({ refreshToken }) => Effect.ignore(revoke(credentials, refreshToken)), {
-	concurrency: "unbounded",
-	discard: true
-});
-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, () => administrationIdentifier(origin));
-	const kept = yield* readCredentials();
-	const previous = Option.filter(kept, (credentials) => credentials.url === origin);
-	const clientId = yield* Option.match(previous, {
-		onSome: (credentials) => Effect.succeed(credentials.clientId),
-		onNone: () => register(origin, server, registeredRedirect)
-	});
-	const { port, received } = yield* listen;
-	const redirectUri = `http://127.0.0.1:${port}/callback`;
-	const scope = withRefresh(asked);
-	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,
-		orElse: () => Effect.fail(new OAuthError({ message: "Sign-in: nobody approved it within five minutes" }))
-	}));
-	const tokens = yield* exchangeCode(origin, server, clientId, callback, {
-		state,
-		verifier,
-		redirectUri
-	}, resource);
-	if (tokens.refresh_token === void 0) return yield* new OAuthError({ message: "Sign-in: the issuer issued no refresh token" });
-	const signIn = {
-		resource,
-		scope: tokens.scope ?? scope,
-		accessToken: tokens.access_token,
-		refreshToken: tokens.refresh_token,
-		expiresAt: expiry(tokens)
-	};
-	if (Option.isSome(kept) && Option.isNone(previous)) {
-		yield* revokeAll(kept.value, kept.value.signIns);
-		yield* removeCredentials();
-	}
-	yield* saveSignIn(Option.getOrElse(previous, () => ({
-		url: origin,
-		server: {
-			issuer: server.issuer,
-			token_endpoint: server.token_endpoint,
-			revocation_endpoint: server.revocation_endpoint
-		},
-		clientId,
-		signIns: []
-	})), signIn);
-	return {
-		url: origin,
-		resource,
-		scope: signIn.scope
-	};
-}, Effect.scoped);
-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.` });
-	if (Date.parse(signIn.expiresAt) - Date.now() > 6e4) return signIn.accessToken;
-	const tokens = yield* refresh(credentials, signIn.refreshToken, resource).pipe(Effect.mapError((error) => new OAuthError({ message: `${error.message}. Run \`${loginHint(credentials.url, resource, signIn.scope)}\` again.` })));
-	const refreshed = {
-		...signIn,
-		scope: tokens.scope ?? signIn.scope,
-		accessToken: tokens.access_token,
-		refreshToken: tokens.refresh_token ?? signIn.refreshToken,
-		expiresAt: expiry(tokens)
-	};
-	yield* saveSignIn(credentials, refreshed);
-	return refreshed.accessToken;
-});
-const logout = Effect.fn("Cli.logout")(function* (resource) {
-	const stored = yield* readCredentials();
-	if (Option.isNone(stored)) {
-		yield* removeCredentials();
-		return { signedOut: false };
-	}
-	const credentials = stored.value;
-	const leaving = credentials.signIns.filter((signIn) => Option.match(resource, {
-		onNone: () => true,
-		onSome: (named) => signIn.resource === named
-	}));
-	const staying = credentials.signIns.filter((signIn) => !leaving.includes(signIn));
-	yield* revokeAll(credentials, leaving);
-	yield* staying.length === 0 ? removeCredentials() : writeCredentials({
-		...credentials,
-		signIns: staying
-	});
-	return { signedOut: leaving.length > 0 };
-});
+var version = "0.25.0";
 //#endregion
 //#region src/main.ts
 const refused = (error) => new CliError.UserError({
@@ -687,41 +408,63 @@ const refused = (error) => new CliError.UserError({
 	userMessage: error.message
 });
 const json = (value) => Console.log(JSON.stringify(value, null, 2));
-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);
-const scopeFor = Effect.fn("Cli.scopeFor")(function* (resource, scope) {
-	if (Option.isSome(scope)) return scope.value;
-	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,
-		userMessage: message
-	});
-});
+const urlArgument = (description) => Argument.String("url").pipe(Argument.withDescription(description), Argument.optional);
+const browserOpener = (url) => {
+	switch (process.platform) {
+		case "darwin": return ["open", [url]];
+		case "win32": return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+		default: return ["xdg-open", [url]];
+	}
+};
+const openInBrowser = (page) => Effect.sync(() => {
+	const [command, args] = browserOpener(page.href);
+	spawn(command, args, {
+		stdio: "ignore",
+		detached: true
+	}).on("error", () => void 0).unref();
+});
+const approve = (browser) => (page) => browser ? Effect.andThen(Effect.sync(() => process.stderr.write(`Approve the sign-in in your browser. If it did not open, open this URL:\n\n  ${page.href}\n\n`)), openInBrowser(page)) : Effect.sync(() => process.stderr.write(`Open this URL in your browser to approve the sign-in:\n\n  ${page.href}\n\n`));
 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 "${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."));
-const signedIn = Effect.gen(function* () {
-	const stored = yield* readCredentials().pipe(Effect.mapError(refused));
-	if (Option.isNone(stored)) return yield* new CliError.UserError({
-		cause: "not signed in",
-		userMessage: "Not signed in: run `clankerauth login <url>` first."
+	url: Argument.String("url").pipe(Argument.withDescription("The resource to sign in to: an application's URL, such as https://notes.example, or the issuer's origin, its CLANKERAUTH_BASE_URL, for administration")),
+	scope: Flag.String("scope").pipe(Flag.withDescription("The scopes to ask for, space-separated: every scope the resource publishes by default"), Flag.optional),
+	noBrowser: Flag.Boolean("no-browser").pipe(Flag.withDescription("Print the approval URL without opening it in the browser"), Flag.withDefault(false))
+}, ({ url, scope, noBrowser }) => Credentials.signIn(url, {
+	scope: Option.getOrUndefined(scope),
+	approve: approve(!noBrowser)
+}).pipe(Effect.mapError(refused), Effect.flatMap(json))).pipe(Command.withDescription("Sign in as the issuer's owner to a resource: approve the page it opens in the browser, or the URL it prints. The resource's issuer and scopes are read from its /.well-known/oauth-protected-resource. Sign-ins are kept in ~/.config/clankerauth, each beside the others, whatever its issuer."));
+const logoutCommand = Command.make("logout", { url: urlArgument("Sign out of the resource this URL is under alone") }, ({ url }) => Credentials.signOut(Option.getOrUndefined(url)).pipe(Effect.mapError(refused), Effect.flatMap(json))).pipe(Command.withDescription("Revoke the sign-ins, or the one to the resource a URL is under, and forget them."));
+const notSignedIn = new CliError.UserError({
+	cause: "not signed in",
+	userMessage: "Not signed in: run `clankerauth login <url>` first."
+});
+const administrationSignIn = Effect.gen(function* () {
+	const named = yield* Config.option(Config.String("CLANKERAUTH_URL")).pipe(Effect.mapError(refused));
+	if (Option.exists(named, (url) => !URL.canParse(url))) return yield* new CliError.UserError({
+		cause: "CLANKERAUTH_URL",
+		userMessage: "CLANKERAUTH_URL is no URL: set it to the issuer's origin, its CLANKERAUTH_BASE_URL."
 	});
-	return stored.value;
-});
-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, () => 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."));
-const administrationClient = Effect.gen(function* () {
-	const credentials = yield* signedIn;
-	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)));
-});
-const administration = Administration.map((action) => ActionCli.remoteCommand(OwnerHttp, action).pipe(Command.provideEffect(HttpClient.HttpClient, administrationClient)));
+	const kept = (yield* Credentials.list().pipe(Effect.mapError(refused))).filter((signIn) => signIn.resource === administrationIdentifier(signIn.url)).filter((signIn) => Option.match(named, {
+		onNone: () => true,
+		onSome: (url) => new URL(url).origin === signIn.url
+	}));
+	const [only, ...others] = kept;
+	if (only === void 0) return yield* notSignedIn;
+	if (others.length > 0) return yield* new CliError.UserError({
+		cause: "several issuers",
+		userMessage: `Signed in to administration at ${kept.map((signIn) => signIn.url).join(", ")}: name one with CLANKERAUTH_URL.`
+	});
+	return only;
+});
+const tokenCommand = Command.make("token", { url: urlArgument("An address under the resource whose token to print, such as the application's URL; administration by default") }, ({ url }) => Effect.gen(function* () {
+	const named = Option.isSome(url) ? url.value : (yield* administrationSignIn).resource;
+	const token = yield* Credentials.token({ url: named }).pipe(Effect.mapError(refused));
+	yield* Effect.sync(() => process.stdout.write(`${Redacted.value(token)}\n`));
+})).pipe(Command.withDescription("Print a current access token for the resource signed in to that a URL is under, refreshing it first when it has expired."));
+const administrationClient = Effect.flatMap(administrationSignIn, (signIn) => ActionHttp.client(OwnerHttp, {
+	baseUrl: signIn.url,
+	transformClient: (client) => HttpClient.catchTag(Credentials.authorizing({ url: signIn.resource })(client), ["SignInRequired", "TokenUnavailable"], (error) => Effect.fail(refused(error)))
+}));
+const administration = Administration.map((action) => ActionCli.remoteCommand(OwnerHttp, action, { client: 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,
 	logoutCommand,

package/package.json

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