@gjermundgaraba/clankerauth 0.0.0-stage → 0.17.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gjermund Garaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @gjermundgaraba/clankerauth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+clankerauth login https://clankerauth.home.example
+clankerauth list-clients
+clankerauth create-api-key --name "notes sync" \
+  --permissions '{"https://notes.home.example/":["notes:read"]}' --expires-at null
+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.
+
+## 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:
+
+```sh
+clankerauth create-api-key --name "machine" \
+  --permissions '{"https://creds.home.example/":["creds:machine"]}' --expires-at null \
+  | jq -r .key > key
+```
+
+MIT licensed.

package/dist/main.mjs

@@ -0,0 +1,761 @@
+#!/usr/bin/env node
+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";
+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 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
+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.
+*/
+const errors = [
+	BadRequest,
+	NotFound,
+	Conflict,
+	TooManyRequests,
+	InternalServerError,
+	ServiceUnavailable
+];
+[...errors, Action.Forbidden];
+/**
+* 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.
+*/
+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
+});
+/**
+* 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 SetupInput = Schema.Struct({
+	email: Schema.String,
+	password: Schema.String
+});
+const ClientAuthMethod = Schema.Literals([
+	"none",
+	"client_secret_basic",
+	"client_secret_post"
+]);
+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. */
+const ClientInput = Schema.Struct({
+	client_name: Schema.String,
+	redirect_uris: Schema.Array(Schema.String),
+	resources: ResourceSelection,
+	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,
+	redirect_uris: Schema.Array(Schema.String),
+	application_type: ApplicationType
+});
+const ClientId = Schema.Struct({ client_id: Schema.String });
+/** Without a resource, every authorization the client holds. */
+const ClientRevokeInput = Schema.Struct({
+	client_id: Schema.String,
+	resource: Schema.optional(Schema.String)
+});
+const ClientBlockInput = Schema.Struct({
+	client_id: Schema.String,
+	blocked: Schema.Boolean
+});
+const Client = Schema.Struct({
+	onboarding: Schema.optional(Schema.Literals([
+		"managed",
+		"dcr",
+		"cimd"
+	])),
+	blocked: Schema.optional(Schema.Boolean),
+	client_id: Schema.String,
+	client_name: Schema.optional(Schema.String),
+	redirect_uris: Schema.Array(Schema.String),
+	token_endpoint_auth_method: Schema.optional(Schema.String),
+	application_type: Schema.optional(Schema.NullOr(Schema.String)),
+	scope: Schema.optional(Schema.String),
+	grant_types: Schema.optional(Schema.Array(Schema.String))
+});
+const ClientCredentials = Client.pipe(Schema.fieldsAssign({
+	client_secret: Schema.optional(Schema.String),
+	client_secret_expires_at: Schema.optional(Schema.Number)
+}));
+const Resource = Schema.Struct({
+	identifier: Schema.String,
+	name: Schema.String,
+	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" })),
+	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 });
+const ClientAccess = Schema.Struct({
+	client_id: Schema.String,
+	resource: Schema.String
+});
+const ClientAccessInput = Schema.Struct({
+	client_id: Schema.String,
+	resources: ResourceSelection
+});
+const ClientAccessResult = Schema.Struct({ clientAccess: Schema.Array(ClientAccess) });
+const KeyPermissions = Schema.Record(Schema.String, Schema.Array(Schema.String));
+/**
+* Permissions as the owner grants them: at least one resource, each with scopes named once.
+* A stored key's are `KeyPermissions`, which a key whose permissions no longer decode is
+* listed with, empty.
+*/
+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
+* managed client skips consent, so `approvedAt` is null for it and it shows only while it
+* holds a refresh token. `scopes` are the consent's, else the newest token's.
+* `refreshedAt` is when the newest live refresh token was issued, at sign-in or on refresh.
+*/
+const Connection = Schema.Struct({
+	client_id: Schema.String,
+	resource: Schema.String,
+	scopes: Schema.Array(Schema.String),
+	approvedAt: Schema.NullOr(Timestamp),
+	refreshedAt: Schema.NullOr(Timestamp)
+});
+const ApiKeyInput = Schema.Struct({
+	name: KeyName,
+	permissions: KeyGrants,
+	expiresAt: Schema.NullOr(Timestamp)
+});
+const ApiKeyId = Schema.Struct({ keyId: Schema.String });
+const ApiKeyUpdate = Schema.Struct({
+	keyId: Schema.String,
+	name: Schema.optional(KeyName),
+	permissions: Schema.optional(KeyGrants),
+	enabled: Schema.optional(Schema.Boolean)
+});
+const MachineKey = Schema.Struct({
+	keyId: Schema.String,
+	name: Schema.String,
+	enabled: Schema.Boolean,
+	permissions: KeyPermissions,
+	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 IssuerActions = [
+	Action.make("setupStatus", {
+		description: "Check whether the issuer needs its first owner account.",
+		readOnly: true,
+		...anyone,
+		success: Schema.Struct({ required: Schema.Boolean })
+	}),
+	Action.make("setupOwner", {
+		description: "Create the first owner account.",
+		readOnly: false,
+		...anyone,
+		input: SetupInput,
+		success: Schema.Struct({ created: Schema.Boolean }).pipe(HttpApiSchema.status(201))
+	}),
+	Action.make("keyList", {
+		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,
+		input: Schema.Struct({ resource: Schema.String }),
+		success: Schema.Struct({ list: Schema.String })
+	})
+];
+const ClientListResult = Schema.Struct({
+	clients: Schema.Array(Client),
+	resources: Schema.Array(ResourceSummary),
+	clientAccess: Schema.Array(ClientAccess),
+	connections: Schema.Array(Connection),
+	email: Schema.String,
+	issuer: Schema.String
+});
+const Administration = [
+	Action.make("listClients", {
+		description: "List clients, resources, managed clients' resource access (what they may obtain), and every client's connections (what it holds).",
+		readOnly: true,
+		...owned,
+		success: ClientListResult
+	}),
+	Action.make("createClient", {
+		description: "Register a first-party OAuth client. Returns its secret once when confidential.",
+		readOnly: false,
+		...owned,
+		input: ClientInput,
+		success: ClientCredentials.pipe(HttpApiSchema.status(201))
+	}),
+	Action.make("updateClient", {
+		description: "Rename a first-party client or change its redirect URIs and application type.",
+		readOnly: false,
+		...owned,
+		input: ClientUpdateInput,
+		success: Client
+	}),
+	Action.make("deleteClient", {
+		description: "Delete a client and its stored authorization. An automatic client can register again; block it to keep it out.",
+		readOnly: false,
+		...owned,
+		input: ClientId,
+		success: Schema.Struct({ deleted: Schema.Boolean })
+	}),
+	Action.make("revokeClient", {
+		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,
+		input: ClientRevokeInput,
+		success: Schema.Struct({ revoked: Schema.Boolean })
+	}),
+	Action.make("blockClient", {
+		description: "Block or unblock OAuth authorization for a client.",
+		readOnly: false,
+		...owned,
+		input: ClientBlockInput,
+		success: Schema.Struct({ blocked: Schema.Boolean })
+	}),
+	Action.make("rotateClientSecret", {
+		description: "Rotate a confidential client secret. Returns the new secret once.",
+		readOnly: false,
+		...owned,
+		input: ClientId,
+		success: ClientCredentials
+	}),
+	Action.make("setClientAccess", {
+		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,
+		input: ClientAccessInput,
+		success: ClientAccessResult
+	}),
+	Action.make("createResource", {
+		description: "Create an OAuth resource and its scopes.",
+		readOnly: false,
+		...owned,
+		input: ResourceInput,
+		success: Resource.pipe(HttpApiSchema.status(201))
+	}),
+	Action.make("updateResource", {
+		description: "Update an OAuth resource and its scopes.",
+		readOnly: false,
+		...owned,
+		input: ResourceInput,
+		success: Resource
+	}),
+	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.",
+		readOnly: false,
+		...owned,
+		input: ResourceId,
+		success: Schema.Struct({ deleted: Schema.Boolean })
+	}),
+	Action.make("listApiKeys", {
+		description: "List API key metadata without secret values.",
+		readOnly: true,
+		...owned,
+		success: Schema.Struct({ keys: Schema.Array(MachineKey) })
+	}),
+	Action.make("createApiKey", {
+		description: "Create a scoped API key. Returns its secret once.",
+		readOnly: false,
+		...owned,
+		input: ApiKeyInput,
+		success: MachineKey.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,
+		input: ApiKeyUpdate,
+		success: MachineKey
+	}),
+	Action.make("deleteApiKey", {
+		description: "Delete an API key.",
+		readOnly: false,
+		...owned,
+		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.
+*/
+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.17.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);
+/** 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);
+	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")));
+/**
+* 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, 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
+});
+/** 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) {
+		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 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 = (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 = (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 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";
+/** 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) => {
+		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();
+}));
+/** 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 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 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();
+	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);
+/**
+* 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.` });
+	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;
+});
+/**
+* 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
+	});
+	return { signedOut: leaving.length > 0 };
+});
+//#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;
+	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, 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."
+	});
+	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, 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);
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@gjermundgaraba/clankerauth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.17.1",
+  "description": "The clankerauth command line: sign in to an issuer as its owner and administer it over HTTP.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gjermundgaraba/clankerauth.git",
+    "directory": "apps/cli"
+  },
+  "bin": {
+    "clankerauth": "./dist/main.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.2",
+    "@gjermundgaraba/effect-actions": "0.11.0",
+    "effect": "4.0.2",
+    "oauth4webapi": "3.8.8"
+  },
+  "devDependencies": {
+    "@clankerauth/admin-api": "0.1.0",
+    "@gjermundgaraba/clankerauth-dev": "0.17.1",
+    "@types/node": "26.6.4",
+    "typescript": "7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp pack && vp test"
+  }
 }