@gjermundgaraba/clankerauth

中文文档
0.35.1发布于 2026/11/11MITES Module构建来源已验证近 30 天下载 3531

The clankerauth command line: sign in to an issuer as its owner and administer it over HTTP.

原始使用文档

@gjermundgaraba/clankerauth

The clankerauth command: sign in to a 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.

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 <url> signs in to the resource url identifies, reading it from its /.well-known/oauth-protected-resource: the issuer's own origin, CLANKERAUTH_BASE_URL, publishes administration, and an application's URL publishes its resource. It then discovers the issuer that resource names; registers the command there as a native OAuth client, a new one for each sign-in; opens the approval page in the browser and prints its URL on stderr, for a terminal with no browser to open, or alone with --no-browser; and listens for the redirect on a loopback port. It asks for every scope the resource publishes, clankerauth:read clankerauth:write for administration, unless --scope names fewer: --scope clankerauth:read lists and never changes. Beside them it asks for offline_access, alone for a resource that publishes no scopes. A resource must publish that document, and so be identified by an http: or https: URL, to be signed in to.

The sign-ins are kept in $XDG_CONFIG_HOME/clankerauth/sign-ins.json, ~/.config/clankerauth/sign-ins.json by default, readable by their owner alone: one per resource, each with its own issuer, so signing in at a second issuer leaves the first's alone. A file the command cannot read, such as one another version wrote, counts as signed out and the next login replaces it. A login to a resource already signed in to replaces that sign-in and revokes it. A command refreshes an access token as it is about to expire and saves the rotated refresh token, so a sign-in lasts while it is used at least every 30 days; when the issuer refuses a refresh, the error names the login that asks for the same scopes again. Every change to the file holds its lock, so commands and programs running at once refresh an expired sign-in once, and logout revokes the refresh token that is current. logout revokes every sign-in and deletes the file, and logout <url> the one whose resource that URL is under alone.

Administration commands act at the issuer of the one administration sign-in kept. Signed in to administration at several issuers, name one with CLANKERAUTH_URL, its origin; a value that 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:

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.

Tokens for other commands

token <url> prints a current access token for the resource signed in to that the URL is under, the most specific when several are, and nothing else, refreshing it first when it is about to expire; without a URL it prints administration's. Another command, or a script, gets its bearer token from there instead of keeping a key; a program written with Effect uses token of @gjermundgaraba/clankerauth-sdk/credentials instead, which reads and refreshes the same sign-in:

clankerauth login https://notes.home.example
curl -H "authorization: Bearer $(clankerauth token https://notes.home.example/api/list-notes)" \
  https://notes.home.example/api/list-notes
clankerauth logout https://notes.home.example

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:

clankerauth create-api-key --name "machine" \
  --permissions '{"https://creds.home.example/":["creds:machine"]}' --expires-at null \
  | jq -r .key > key

MIT licensed.

版本与发布记录

@gjermundgaraba/clankerauth 共发布 29 个版本,首次发布于 2026/10/09;过去 12 个月发布了 29 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.35.1latest2026/11/115 天前
0.35.02026/11/115 天前
0.34.02026/11/0610 天前
0.33.12026/11/0511 天前
0.33.02026/11/0214 天前
0.32.02026/11/0115 天前

关于 @gjermundgaraba/clankerauth 的常见问题

@gjermundgaraba/clankerauth 是什么?

The clankerauth command line: sign in to an issuer as its owner and administer it over HTTP.

如何安装 @gjermundgaraba/clankerauth?

在项目目录运行 npm install @gjermundgaraba/clankerauth,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 clankerauth,可以用 npx clankerauth 直接运行。

@gjermundgaraba/clankerauth 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gjermundgaraba__clankerauth 是否存在。

@gjermundgaraba/clankerauth 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gjermundgaraba/clankerauth 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=26.13.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gjermundgaraba/clankerauth 可以商用吗?

@gjermundgaraba/clankerauth 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gjermundgaraba/clankerauth 的下载量有多少?

根据 npm 官方下载统计,@gjermundgaraba/clankerauth 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,531 次,日均约 118 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gjermundgaraba/clankerauth 还在维护吗?

最新版本 0.35.1 发布于 2026/11/11(5 天前);至今共发布 29 个版本,其中过去 12 个月发布了 29 个;首次发布于 2026/10/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。