@gjermundgaraba/clankerauth 0.16.0 → 0.18.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 and run every administration action over HTTP. 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.16.0 or later.
 
 ```sh
 npm install --global @gjermundgaraba/clankerauth
@@ -12,7 +12,21 @@ clankerauth create-api-key --name "notes sync" \
 clankerauth logout
 ```
 
-`login` discovers the issuer, registers the command as a native OAuth client the first time, and asks the owner to approve in the browser: it prints the approval URL on stderr, opens it unless `--no-browser`, and listens for the redirect on a loopback port. `--read-only` asks for `clankerauth:read` alone, which lists and never changes. The sign-in is kept in `$XDG_CONFIG_HOME/clankerauth/credentials.json`, `~/.config/clankerauth/credentials.json` by default, readable by its owner alone. A command refreshes the access token once it has expired and saves the rotated refresh token. `logout` revokes the sign-in and deletes the file.
+`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.
+
+## 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:
+
+```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/)" \
+  https://notes.home.example/api/list-notes
+clankerauth logout --resource 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:
 

package/dist/main.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Console, Context, Deferred, Effect, Match, Option, Schema } from "effect";
+import { Console, Context, Deferred, Effect, Option, Schema } from "effect";
 import { Argument, CliError, Command, Flag } from "effect/cli";
 import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
@@ -8,12 +8,12 @@ import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 import { HttpApiSchema, HttpApiSecurity } from "effect/http-api";
-import { createHash, randomBytes } from "node:crypto";
+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 { spawn } from "node:child_process";
 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 }) {};
@@ -365,46 +365,53 @@ const OwnerHttp = ActionHttp.make(Administration, {
 });
 //#endregion
 //#region package.json
-var version = "0.16.0";
+var version = "0.18.0";
 //#endregion
 //#region src/credentials.ts
-/** The kept sign-in cannot be read or written. */
+/** 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}` });
 /**
-* One owner sign-in: the issuer it is for, the client it registered as, and its tokens. The
-* access token lasts fifteen minutes and the refresh token rotates on every use, so the file
-* is rewritten whenever a command refreshes.
+* 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 Credentials = Schema.Struct({
-	/** The issuer's origin, `CLANKERAUTH_BASE_URL`: where `/api/owner/<action>` is served. */
-	url: Schema.String,
-	/** The administration resource, the token audience: the issuer's origin root. */
+const SignIn = Schema.Struct({
+	/** The token audience: a resource identifier, such as `https://notes.home.example/`. */
 	resource: Schema.String,
-	tokenEndpoint: Schema.String,
-	/** Where `logout` revokes the refresh token; null when the issuer publishes none. */
-	revocationEndpoint: Schema.NullOr(Schema.String),
-	clientId: 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);
-/** Where the sign-in is kept: `$XDG_CONFIG_HOME/clankerauth`, or `~/.config/clankerauth`. */
+/** 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-in, if there is one. A file that does not decode is a failure, not a sign-out. */
-const readCredentials = Effect.fn("Credentials.read")(function* () {
-	const text = yield* Effect.tryPromise(() => readFile(credentialsPath(), "utf8")).pipe(Effect.map(Option.some), Effect.catchIf((error) => error.cause instanceof Error && "code" in error.cause && error.cause.code === "ENOENT", () => Effect.succeed(Option.none())));
-	return yield* Option.match(text, {
-		onNone: () => Effect.succeedNone,
-		onSome: (json) => Effect.map(Schema.decodeEffect(CredentialsJson)(json), Option.some)
-	});
-}, Effect.mapError(failed("Cannot read")));
 /**
-* Replace the sign-in, readable by its owner alone. Written beside it and renamed over it, so
-* a command interrupted mid-write never leaves a refresh token half-saved.
+* 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();
@@ -419,108 +426,136 @@ 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);
+	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 or a refresh cannot go on from. */
+/** 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 }) {};
-/** RFC 9728: where a resource says its tokens come from. */
-const ProtectedResource = Schema.Struct({
-	resource: Schema.String,
-	authorization_servers: Schema.NonEmptyArray(Schema.String)
-});
-/** RFC 8414: the endpoints a sign-in uses. */
-const AuthorizationServer = Schema.Struct({
+/** 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.optionalKey(Schema.String)
-});
-const Registration = Schema.Struct({ client_id: Schema.String });
-const Tokens = Schema.Struct({
-	access_token: Schema.String,
-	refresh_token: Schema.String,
-	expires_in: Schema.Number,
-	scope: Schema.optionalKey(Schema.String)
-});
-/** An OAuth error response's fields, when the issuer sent one. */
-const ErrorBody = Schema.Struct({
-	error: Schema.String,
-	error_description: Schema.optionalKey(Schema.String)
-});
-/** Send `request` and decode its JSON as `schema`, failing with what the issuer said. */
-const exchange = (what, schema, request) => Effect.gen(function* () {
-	const response = yield* Effect.tryPromise({
-		try: request,
-		catch: (error) => new OAuthError({ message: `${what}: the issuer cannot be reached (${String(error)})` })
-	});
-	const text = yield* Effect.promise(() => response.text());
-	if (!response.ok) return yield* new OAuthError({ message: `${what}: ${Option.match(Schema.decodeUnknownOption(Schema.fromJsonString(ErrorBody))(text), {
-		onNone: () => `HTTP ${response.status}`,
-		onSome: (body) => body.error_description === void 0 ? body.error : `${body.error}: ${body.error_description}`
-	})}` });
-	return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(text).pipe(Effect.mapError((error) => new OAuthError({ message: `${what}: unexpected answer (${error.message})` })));
+	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 })
 });
 /**
-* The issuer at `url` as a sign-in reaches it: its administration resource, published at the
-* origin root's RFC 9728 document, and the authorization server that resource names.
+* 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) {
+		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;
+};
+/** 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 resource = yield* exchange("Discovery", ProtectedResource, () => fetch(new URL("/.well-known/oauth-protected-resource", url)));
-	const issuer = new URL(resource.authorization_servers[0]);
-	const metadata = new URL(`/.well-known/oauth-authorization-server${issuer.pathname === "/" ? "" : issuer.pathname}`, issuer);
-	const server = yield* exchange("Discovery", AuthorizationServer, () => fetch(metadata));
-	return {
-		resource: resource.resource,
-		server
-	};
+	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})` })));
 });
 /**
 * 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 = Effect.fn("OAuth.register")(function* (server, redirectUri) {
-	return (yield* exchange("Registration", Registration, () => fetch(server.registration_endpoint, {
-		method: "POST",
-		headers: { "content-type": "application/json" },
-		body: JSON.stringify({
-			client_name: "clankerauth CLI",
-			redirect_uris: [redirectUri],
-			application_type: "native",
-			token_endpoint_auth_method: "none",
-			grant_types: ["authorization_code", "refresh_token"],
-			response_types: ["code"]
-		})
-	}))).client_id;
-});
-/** Ask the token endpoint for tokens, with the grant's own form fields. */
-const token = (what, endpoint, form) => exchange(what, Tokens, () => fetch(endpoint, {
-	method: "POST",
-	headers: { "content-type": "application/x-www-form-urlencoded" },
-	body: form
-}));
+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));
+/**
+* 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 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)
+	}));
+});
+/** 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 = (endpoint, clientId, refreshToken) => Effect.tryPromise(() => fetch(endpoint, {
-	method: "POST",
-	headers: { "content-type": "application/x-www-form-urlencoded" },
-	body: new URLSearchParams({
-		token: refreshToken,
-		token_type_hint: "refresh_token",
-		client_id: clientId
-	})
-}));
+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
-/** What the owner grants: everything, or only listing. */
-const scopes = (readOnly) => readOnly ? "clankerauth:read offline_access" : "clankerauth:read clankerauth:write offline_access";
+/** 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 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>"}"`}`;
+};
 /** 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";
-const expiry = (tokens) => new Date(Date.now() + tokens.expires_in * 1e3).toISOString();
-/** What the callback page tells the browser; the terminal has the details. */
-const page = (heading) => `<!doctype html><meta charset="utf-8"><title>clankerauth</title><p>${heading}</p>`;
+/** 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();
@@ -530,15 +565,8 @@ const listen = Effect.acquireRelease(Effect.gen(function* () {
 			response.writeHead(404).end();
 			return;
 		}
-		const query = url.searchParams;
-		response.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page(query.has("code") ? "Signed in. You can close this tab." : "Sign-in failed. The terminal says why."));
-		Deferred.doneUnsafe(received, Effect.succeed({
-			code: query.get("code"),
-			state: query.get("state"),
-			iss: query.get("iss"),
-			error: query.get("error"),
-			errorDescription: query.get("error_description")
-		}));
+		response.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page);
+		Deferred.doneUnsafe(received, Effect.succeed(url.searchParams));
 	});
 	return {
 		server,
@@ -552,40 +580,32 @@ const listen = Effect.acquireRelease(Effect.gen(function* () {
 	server.closeAllConnections();
 	server.close();
 }));
-/** Open `url` in the default browser, if the platform has a way to; never fails. */
-const openBrowser = (url) => Effect.sync(() => {
-	const [command, ...args] = Match.value(process.platform).pipe(Match.when("darwin", () => ["open", url]), Match.when("win32", () => [
-		"cmd",
-		"/c",
-		"start",
-		"",
-		url
-	]), Match.orElse(() => ["xdg-open", url]));
-	try {
-		spawn(command ?? "open", args, {
-			stdio: "ignore",
-			detached: true
-		}).on("error", () => {}).unref();
-	} catch {}
+/** 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: discover it, register this CLI once per
-* issuer, send the owner to approve in the browser, and keep the tokens. What it prints on
-* stderr is for the person; stdout gets only the result.
+* 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, readOnly, browser) {
+const login = Effect.fn("Cli.login")(function* (url, target, asked) {
 	const origin = new URL(url).origin;
-	const { resource, server } = yield* discover(origin);
-	const previous = yield* readCredentials();
-	const clientId = yield* Option.match(Option.filter(previous, (credentials) => credentials.url === origin), {
+	const server = yield* discover(origin);
+	const resource = Option.getOrElse(target, () => administrationOf(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(server, registeredRedirect)
+		onNone: () => register(origin, server, registeredRedirect)
 	});
 	const { port, received } = yield* listen;
 	const redirectUri = `http://127.0.0.1:${port}/callback`;
-	const verifier = randomBytes(32).toString("base64url");
-	const state = randomBytes(16).toString("base64url");
-	const scope = scopes(readOnly);
+	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,
@@ -593,81 +613,90 @@ const login = Effect.fn("Cli.login")(function* (url, readOnly, browser) {
 		response_type: "code",
 		scope,
 		resource,
-		code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+		code_challenge: yield* Effect.promise(() => oauth.calculatePKCECodeChallenge(verifier)),
 		code_challenge_method: "S256",
 		state
 	}).toString();
-	yield* Effect.sync(() => process.stderr.write(`Approve the sign-in in your browser:\n\n  ${authorization.href}\n\n`));
-	if (browser) yield* openBrowser(authorization.href);
+	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" }))
 	}));
-	if (callback.state !== state) return yield* new OAuthError({ message: "Sign-in: the redirect's state does not match" });
-	if (callback.iss !== null && callback.iss !== server.issuer) return yield* new OAuthError({ message: `Sign-in: the redirect came from ${callback.iss}` });
-	if (callback.code === null) return yield* new OAuthError({ message: `Sign-in: ${callback.error ?? "no code"}${callback.errorDescription ? `: ${callback.errorDescription}` : ""}` });
-	const tokens = yield* token("Sign-in", server.token_endpoint, new URLSearchParams({
-		grant_type: "authorization_code",
-		client_id: clientId,
-		code: callback.code,
-		code_verifier: verifier,
-		redirect_uri: redirectUri,
-		resource
-	}));
-	const credentials = {
-		url: origin,
+	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,
-		tokenEndpoint: server.token_endpoint,
-		revocationEndpoint: server.revocation_endpoint ?? null,
-		clientId,
 		scope: tokens.scope ?? scope,
 		accessToken: tokens.access_token,
 		refreshToken: tokens.refresh_token,
 		expiresAt: expiry(tokens)
 	};
-	yield* writeCredentials(credentials);
+	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,
-		scope: credentials.scope
+		resource,
+		scope: signIn.scope
 	};
 }, Effect.scoped);
 /**
-* The sign-in's access token, 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.
+* 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) {
-	if (Date.parse(credentials.expiresAt) - Date.now() > 6e4) return {
-		credentials,
-		token: credentials.accessToken
-	};
-	const tokens = yield* token("Refresh", credentials.tokenEndpoint, new URLSearchParams({
-		grant_type: "refresh_token",
-		client_id: credentials.clientId,
-		refresh_token: credentials.refreshToken,
-		resource: credentials.resource
-	})).pipe(Effect.mapError((error) => new OAuthError({ message: `${error.message}. Run \`clankerauth login ${credentials.url}\` again.` })));
+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 = {
-		...credentials,
-		scope: tokens.scope ?? credentials.scope,
+		...signIn,
+		scope: tokens.scope ?? signIn.scope,
 		accessToken: tokens.access_token,
-		refreshToken: tokens.refresh_token,
+		refreshToken: tokens.refresh_token ?? signIn.refreshToken,
 		expiresAt: expiry(tokens)
 	};
-	yield* writeCredentials(refreshed);
-	return {
-		credentials: refreshed,
-		token: refreshed.accessToken
-	};
+	yield* saveSignIn(credentials, refreshed);
+	return refreshed.accessToken;
 });
-/** Forget the sign-in, revoking its refresh token first when the issuer can be reached. */
-const logout = Effect.fn("Cli.logout")(function* () {
-	const credentials = yield* readCredentials();
-	yield* Option.match(credentials, {
-		onNone: () => Effect.void,
-		onSome: ({ revocationEndpoint, clientId, refreshToken }) => revocationEndpoint === null ? Effect.void : Effect.ignore(revoke(revocationEndpoint, clientId, refreshToken))
+/**
+* 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)) {
+		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
 	});
-	yield* removeCredentials();
-	return { signedOut: Option.isSome(credentials) };
+	return { signedOut: leaving.length > 0 };
 });
 //#endregion
 //#region src/main.ts
@@ -677,30 +706,54 @@ const refused = (error) => new CliError.UserError({
 	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;
+	const message = `Name the scopes to ask ${resource.value} for with --scope.`;
+	return yield* new CliError.UserError({
+		cause: message,
+		userMessage: message
+	});
+});
 const loginCommand = Command.make("login", {
-	url: Argument.String("url").pipe(Argument.withDescription("The issuer's origin, such as https://auth.example.com")),
-	readOnly: Flag.Boolean("read-only").pipe(Flag.withDescription("Ask for clankerauth:read alone: list, never change"), Flag.withDefault(false)),
-	browser: Flag.Boolean("browser").pipe(Flag.withDescription("Open the approval page; --no-browser only prints its URL"), Flag.withDefault(true))
-}, ({ url, readOnly, browser }) => login(url, readOnly, browser).pipe(Effect.mapError(refused), Effect.flatMap(json))).pipe(Command.withDescription("Sign in to an issuer as its owner. The sign-in is kept in ~/.config/clankerauth."));
-const logoutCommand = Command.make("logout", {}, () => logout().pipe(Effect.mapError(refused), Effect.flatMap(json))).pipe(Command.withDescription("Revoke the sign-in and forget it."));
-/**
-* The client every administration command calls through: the signed-in issuer's origin and
-* a current access token, refreshed and saved first when it has expired.
-*/
+	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)
+}, ({ 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({
 		cause: "not signed in",
 		userMessage: "Not signed in: run `clankerauth login <url>` first."
 	});
-	const { credentials, token } = yield* accessToken(stored.value).pipe(Effect.mapError(refused));
+	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));
+	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));
 	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, signedIn)));
-const cli = Command.make("clankerauth").pipe(Command.withDescription("Administer a clankerauth issuer as its owner. Results are JSON on stdout; a created key or client secret is in it once."), Command.withSubcommands([
+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,
 	logoutCommand,
+	tokenCommand,
 	...administration
 ]));
 Command.run(cli, { version }).pipe(Effect.provide(FetchHttpClient.layer), Effect.provide(NodeServices.layer), ActionCli.logToStderr, NodeRuntime.runMain);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "The clankerauth command line: sign in to an issuer as its owner and administer it over HTTP.",
   "license": "MIT",
   "repository": {
@@ -19,13 +19,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.2",
-    "@gjermundgaraba/effect-actions": "0.11.0",
-    "effect": "4.0.2"
+    "@effect/platform-node": "4.0.3",
+    "@gjermundgaraba/effect-actions": "0.13.0",
+    "effect": "4.0.3",
+    "oauth4webapi": "3.8.8"
   },
   "devDependencies": {
     "@clankerauth/admin-api": "0.1.0",
-    "@gjermundgaraba/clankerauth-dev": "0.16.0",
+    "@gjermundgaraba/clankerauth-dev": "0.18.0",
     "@types/node": "26.6.4",
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
@@ -36,6 +37,6 @@
   },
   "scripts": {
     "build": "vp pack",
-    "test": "vp test"
+    "test": "vp pack && vp test"
   }
 }