@gjermundgaraba/clankerauth 0.0.0-stage → 0.16.0

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,25 @@
-# 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 and run every administration action over HTTP. 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, 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.
+
+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,708 @@
+#!/usr/bin/env node
+import { Console, Context, Deferred, Effect, Match, 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 { createHash, 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";
+//#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.16.0";
+//#endregion
+//#region src/credentials.ts
+/** The kept sign-in 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.
+*/
+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. */
+	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
+});
+const CredentialsJson = Schema.fromJsonString(Credentials);
+/** Where the sign-in is 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.
+*/
+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 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. */
+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({
+	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})` })));
+});
+/**
+* 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.
+*/
+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
+	};
+});
+/**
+* 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
+}));
+/** 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
+	})
+}));
+//#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 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>`;
+/** 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;
+		}
+		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")
+		}));
+	});
+	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();
+}));
+/** 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 {}
+});
+/**
+* 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.
+*/
+const login = Effect.fn("Cli.login")(function* (url, readOnly, browser) {
+	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), {
+		onSome: (credentials) => Effect.succeed(credentials.clientId),
+		onNone: () => register(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 authorization = new URL(server.authorization_endpoint);
+	authorization.search = new URLSearchParams({
+		client_id: clientId,
+		redirect_uri: redirectUri,
+		response_type: "code",
+		scope,
+		resource,
+		code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+		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);
+	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,
+		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);
+	return {
+		url: origin,
+		scope: credentials.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.
+*/
+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 refreshed = {
+		...credentials,
+		scope: tokens.scope ?? credentials.scope,
+		accessToken: tokens.access_token,
+		refreshToken: tokens.refresh_token,
+		expiresAt: expiry(tokens)
+	};
+	yield* writeCredentials(refreshed);
+	return {
+		credentials: refreshed,
+		token: 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))
+	});
+	yield* removeCredentials();
+	return { signedOut: Option.isSome(credentials) };
+});
+//#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));
+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.
+*/
+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 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([
+	loginCommand,
+	logoutCommand,
+	...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,41 @@
 {
   "name": "@gjermundgaraba/clankerauth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.16.0",
+  "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"
+  },
+  "devDependencies": {
+    "@clankerauth/admin-api": "0.1.0",
+    "@gjermundgaraba/clankerauth-dev": "0.16.0",
+    "@types/node": "26.6.4",
+    "typescript": "7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test"
+  }
 }