@gjermundgaraba/clankerauth 0.27.0 → 0.28.1

package/README.md

@@ -1,6 +1,6 @@
 # @gjermundgaraba/clankerauth
 
-The `clankerauth` command: sign in to a [clankerauth](https://github.com/gjermundgaraba/clankerauth) issuer as its owner, run every administration action over HTTP, and hand other commands access tokens for the issuer's resources. It needs Node 26 or newer and an issuer at 0.24.0 or later.
+The `clankerauth` command: sign in to a [clankerauth](https://github.com/gjermundgaraba/clankerauth) issuer as its owner, run every administration action over HTTP, and hand other commands access tokens for the issuer's resources. It needs Node 26 or newer and an issuer at 0.24.0 or later, or 0.28.0 for an administration key in `CLANKERAUTH_TOKEN`.
 
 ```sh
 npm install --global @gjermundgaraba/clankerauth
@@ -16,7 +16,19 @@ clankerauth logout
 
 The sign-ins are kept in `$XDG_CONFIG_HOME/clankerauth/sign-ins.json`, `~/.config/clankerauth/sign-ins.json` by default, readable by their owner alone: one per resource, each with its own issuer, so signing in at a second issuer leaves the first's alone. A file the command cannot read, such as one another version wrote, counts as signed out and the next `login` replaces it. A `login` to a resource already signed in to replaces that sign-in and revokes it. A command refreshes an access token as it is about to expire and saves the rotated refresh token, so a sign-in lasts while it is used at least every 30 days; when the issuer refuses a refresh, the error names the `login` that asks for the same scopes again. Every change to the file holds its lock, so commands and programs running at once refresh an expired sign-in once, and `logout` revokes the refresh token that is current. `logout` revokes every sign-in and deletes the file, and `logout <url>` the one whose resource that URL is under alone.
 
-Administration commands act at the issuer of the one administration sign-in kept. Signed in to administration at several issuers, name one with `CLANKERAUTH_URL`, its origin; a value that is no URL is refused.
+Administration commands act at the issuer of the one administration sign-in kept. Signed in to administration at several issuers, name one with `CLANKERAUTH_URL`, its origin; a value that names no origin, such as a `mailto:` URL, is refused.
+
+Unattended, such as in a container with no browser or disk to keep a sign-in on, the commands take an administration key, an API key granted on the issuer's origin root, from `CLANKERAUTH_TOKEN` instead, and then act at the issuer `CLANKERAUTH_URL` names, which they require. No sign-in is read or written. The owner creates the key once, signed in:
+
+```sh
+clankerauth create-api-key --name deployer --expires-at null \
+  --permissions '{"https://clankerauth.home.example/":["clankerauth:read","clankerauth:write"]}'
+
+CLANKERAUTH_URL=https://clankerauth.home.example CLANKERAUTH_TOKEN=clankerauth_… \
+  clankerauth list-api-keys
+```
+
+What the key may do, and when a change to it applies, is in [the issuer's README](../../README.md#administer-unattended-with-an-api-key).
 
 ## Tokens for other commands
 

package/dist/main.mjs

@@ -400,7 +400,7 @@ const OwnerHttp = ActionHttp.make(Administration, {
 });
 //#endregion
 //#region package.json
-var version = "0.27.0";
+var version = "0.28.1";
 //#endregion
 //#region src/main.ts
 const refused = (error) => new CliError.UserError({
@@ -437,15 +437,15 @@ const notSignedIn = new CliError.UserError({
 	cause: "not signed in",
 	userMessage: "Not signed in: run `clankerauth login <url>` first."
 });
+const issuerNamed = Config.option(Config.String("CLANKERAUTH_URL")).pipe(Effect.mapError(refused), Effect.map(Option.map((url) => URL.parse(url)?.origin ?? "null")), Effect.flatMap((origin) => Option.contains(origin, "null") ? Effect.fail(new CliError.UserError({
+	cause: "CLANKERAUTH_URL",
+	userMessage: "CLANKERAUTH_URL is no issuer URL: set it to the issuer's origin, its CLANKERAUTH_BASE_URL."
+})) : Effect.succeed(origin)));
 const administrationSignIn = Effect.gen(function* () {
-	const named = yield* Config.option(Config.String("CLANKERAUTH_URL")).pipe(Effect.mapError(refused));
-	if (Option.exists(named, (url) => !URL.canParse(url))) return yield* new CliError.UserError({
-		cause: "CLANKERAUTH_URL",
-		userMessage: "CLANKERAUTH_URL is no URL: set it to the issuer's origin, its CLANKERAUTH_BASE_URL."
-	});
+	const named = yield* issuerNamed;
 	const kept = (yield* Credentials.list().pipe(Effect.mapError(refused))).filter((signIn) => signIn.resource === administrationIdentifier(signIn.url)).filter((signIn) => Option.match(named, {
 		onNone: () => true,
-		onSome: (url) => new URL(url).origin === signIn.url
+		onSome: (origin) => origin === signIn.url
 	}));
 	const [only, ...others] = kept;
 	if (only === void 0) return yield* notSignedIn;
@@ -455,14 +455,31 @@ const administrationSignIn = Effect.gen(function* () {
 	});
 	return only;
 });
+const administrationKey = Config.Redacted("CLANKERAUTH_TOKEN");
+const administrationTarget = Effect.gen(function* () {
+	const given = yield* Config.option(administrationKey).pipe(Effect.mapError(refused));
+	if (Option.isNone(given)) return yield* administrationSignIn;
+	const named = yield* issuerNamed;
+	if (Option.isNone(named)) return yield* new CliError.UserError({
+		cause: "CLANKERAUTH_URL",
+		userMessage: "CLANKERAUTH_TOKEN is set without CLANKERAUTH_URL: set it to the issuer's origin, its CLANKERAUTH_BASE_URL."
+	});
+	return {
+		url: named.value,
+		resource: administrationIdentifier(named.value)
+	};
+});
 const tokenCommand = Command.make("token", { url: urlArgument("An address under the resource whose token to print, such as the application's URL; administration by default") }, ({ url }) => Effect.gen(function* () {
 	const named = Option.isSome(url) ? url.value : (yield* administrationSignIn).resource;
 	const token = yield* Credentials.token({ url: named }).pipe(Effect.mapError(refused));
 	yield* Effect.sync(() => process.stdout.write(`${Redacted.value(token)}\n`));
 })).pipe(Command.withDescription("Print a current access token for the resource signed in to that a URL is under, refreshing it first when it has expired."));
-const administrationClient = Effect.flatMap(administrationSignIn, (signIn) => ActionHttp.client(OwnerHttp, {
-	baseUrl: signIn.url,
-	transformClient: (client) => HttpClient.catchTag(Credentials.authorizing({ url: signIn.resource })(client), ["SignInRequired", "TokenUnavailable"], (error) => Effect.fail(refused(error)))
+const administrationClient = Effect.flatMap(administrationTarget, (target) => ActionHttp.client(OwnerHttp, {
+	baseUrl: target.url,
+	transformClient: (client) => HttpClient.catchTag(Credentials.authorizing({
+		url: target.resource,
+		token: administrationKey
+	})(client), ["SignInRequired", "TokenUnavailable"], (error) => Effect.fail(refused(error)))
 }));
 const administration = Administration.map((action) => ActionCli.remoteCommand(OwnerHttp, action, { client: administrationClient }));
 const cli = Command.make("clankerauth").pipe(Command.withDescription("Administer a clankerauth issuer as its owner, and hand other commands its tokens. Results are JSON on stdout; a created key or client secret is in it once."), Command.withSubcommands([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "The clankerauth command line: sign in to an issuer as its owner and administer it over HTTP.",
   "license": "MIT",
   "repository": {
@@ -21,13 +21,13 @@
   "dependencies": {
     "@effect/platform-node": "4.0.5",
     "@effect/platform-node-shared": "4.0.5",
-    "@gjermundgaraba/clankerauth-sdk": "0.27.0",
+    "@gjermundgaraba/clankerauth-sdk": "0.28.1",
     "@gjermundgaraba/effect-actions": "0.19.0",
     "effect": "4.0.5"
   },
   "devDependencies": {
-    "@gjermundgaraba/clankerauth-admin-api": "0.27.0",
-    "@gjermundgaraba/clankerauth-dev": "0.27.0",
+    "@gjermundgaraba/clankerauth-admin-api": "0.28.1",
+    "@gjermundgaraba/clankerauth-dev": "0.28.1",
     "@types/node": "26.6.5",
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",