@gjermundgaraba/clankerauth-dev

中文文档
0.35.1发布于 2026/11/11MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 3631

Disposable local clankerauth issuer for application development

原始使用文档
文档目录4 节
  1. Provisioning
  2. A workspace that survives a restart
  3. The edge
  4. A fake issuer for tests

@gjermundgaraba/clankerauth-dev

A disposable clankerauth issuer for developing and testing applications that authenticate against one. The package bundles the whole server and dashboard with no dependencies, so it needs only Node 26 or newer.

npm install --save-dev @gjermundgaraba/clankerauth-dev
import { startDisposableIssuer } from "@gjermundgaraba/clankerauth-dev";

const issuer = await startDisposableIssuer({
  resources: [
    {
      identifier: "http://127.0.0.1:8080/",
      name: "Notes",
      scopes: ["notes:read"],
    },
  ],
  client: {
    name: "Notes console",
    redirect: "http://localhost:5173/callback",
    resources: ["http://127.0.0.1:8080/"],
  },
});

issuer.issuer; // OAuth issuer URL, for discovery and token verification
issuer.url; // dashboard origin, sign in with issuer.owner.email and issuer.owner.password
issuer.clientId; // a confidential native client for the given redirect and resources
issuer.clientSecret;

await issuer.close();

Each call listens on a random loopback port, creates a fresh SQLite database and secret in a temporary directory, provisions the owner, the resources and the client in-process through the server's administration module, and returns. Only the returned issuer is reached over HTTP. The client is first party: once the owner is signed in, an authorization request redirects straight to the callback with a code and no consent step. close() drains in-flight requests, closes the database and deletes the directory. Nothing is shared between calls and nothing survives them. A start that fails, for example on an invalid cookieDomain, rejects with ProvisioningError after doing the same, so it leaves no port bound and nothing to close.

Provisioning

The issuer provisions what a test or a development script would otherwise script by hand against its HTTP API:

const key = await issuer.apiKey({
  permissions: { [resource.identifier]: ["notes:read"] },
});

// Needs a cookieDomain: the forward cookie is what a browser holds.
const { cookie, cookies } = await issuer.ownerSession(
  "http://app.notes.localhost:5173"
);
const token = await issuer.ownerToken({
  resource: resource.identifier,
  appOrigin: "http://app.notes.localhost:5173",
});

apiKey returns the secret once. ownerSession mints a session for the owner in process, without the rate-limited sign-in endpoint, so any number of calls and restarts never meet a 429, and seals the forward cookie exactly as /forward-auth/continue does for a browser; cookies is the name/value form a browser-automation context takes. ownerToken runs the same forward-auth check and returns the access token, so a test never assembles a cookie jar. A refused apiKey rejects with ProvisioningError, and a refused ownerSession or ownerToken with ForwardAuthError. Both classes are exported, and each one's _tag is its name.

A workspace that survives a restart

Pass dataDir and a fixed port to keep the issuer's state:

const issuer = await startDisposableIssuer({
  ...options,
  dataDir: ".dev/clankerauth",
  port: 5174,
});

The owner account and password, the signing secret, the registered client and the database are kept in that directory, and provisioning is idempotent, so the next start reuses them: the same sign-in works, API keys minted before still verify, and browser storage keyed by the origin survives. A fixed port is part of that, because the origin is what cookies and registered redirect URIs are keyed by. close() leaves the directory alone. Treat it as the whole secret of the workspace and keep it out of version control. credentials.json is written and read by this package alone and is validated against its schema on every start, so an edited or truncated file is refused rather than half-read. Without dataDir, nothing changes: a temporary directory, a random port, and everything removed by close().

To develop an app behind forward auth, pass a cookieDomain:

const issuer = await startDisposableIssuer({
  resources: [
    {
      identifier: "http://app.notes.localhost:8080/",
      name: "Notes",
      scopes: [],
    },
  ],
  client: {
    name: "Notes console",
    redirect: "http://localhost:5173/callback",
    resources: [],
  },
  cookieDomain: "notes.localhost",
});

issuer.url; // http://clankerauth.notes.localhost:<port>

The issuer then serves /forward-auth?resource=<identifier>, /forward-auth/continue and /forward-auth/logout, and shares its forward cookie with every host under the domain, so serve the app on one, such as app.notes.localhost. Browsers and Node resolve .localhost names to loopback without a hosts-file entry. A signed-in owner's check answers 204 with an Authorization header to copy upstream; without a session, a page navigation (Sec-Fetch-Mode: navigate) is redirected through sign-in and any other request is 401. Without cookieDomain the issuer is http://127.0.0.1:<port> and these routes are not served.

The edge

@gjermundgaraba/clankerauth-dev/edge is the deployment edge for local development: the forward_auth check, and for upgrades a reverse proxy. Do not write one again.

import {
  forwardAuth,
  reserveLoopbackPort,
} from "@gjermundgaraba/clankerauth-dev/edge";

export default defineConfig({
  plugins: [
    forwardAuth({
      issuer: "http://clankerauth.notes.localhost:5174",
      appOrigin: "http://app.notes.localhost:5173",
      resource: "http://app.notes.localhost:5173/",
      sockets: { backend: "http://127.0.0.1:8080", paths: ["/eventlog"] },
      verifiesAuthorization: (path) => path.startsWith("/api/"),
      onError: (error) => console.error("[forward-auth]", error.message),
    }),
  ],
});

Nothing in this package imports Vite, at run time or in its types: the plugin is the plain object Vite accepts. On a plain Node server, attach(server, options) installs the same two halves and returns the request middleware; check(options) and middleware(options) are available on their own.

  • The check uses node:http, never fetch: fetch owns Sec-Fetch-Mode, and that header is what tells the issuer whether a request may be redirected through sign-in. The browser's own header is relayed, along with its cookie, plus x-forwarded-proto, -host and -uri.
  • It has a timeout (5 s by default) and rejects rather than deciding when the issuer is unreachable, too slow, or answers 204 with no Authorization to forward. middleware turns a rejection into a 502 and passes the error to onError; an empty credential is never forwarded upstream.
  • A refusal is relayed as the issuer wrote it: its status, its Location, its WWW-Authenticate, its body and its content type. A script that is not signed in reads {"error":"unauthenticated"} rather than an empty 401, and the challenge names the resource's metadata, so an OAuth client can discover where to sign in.
  • publicPaths defaults to /mcp, /.well-known and /healthz, and a request that already carries an Authorization header is not checked where verifiesAuthorization(path) says the server behind the edge verifies one, by default every path: agents onboard themselves and probes run. A development server verifies nothing, so an edge in front of Vite answers false for the paths Vite serves; otherwise any Authorization value, even x, reaches its pages and modules. Where it answers false, the header is ignored and the issuer's token replaces it.
  • Only a plain path passes unchecked. A path with a dot segment, an encoded ., / or \, or a backslash goes through the check like any other, so a server behind the edge cannot resolve /mcp/../src/main.ts into a page the check never saw. With sockets given, an upgrade on such a path is refused with 400.
  • upgrade only takes the paths in sockets.paths, so a development server keeps its own hot-reload socket; it returns false for everything else, which on a plain Node server means another listener must answer them. Those upgrades are not checked: another listener answers an upgrade as it arrives, and the edge cannot hold it while the issuer decides. Vite refuses a hot-reload upgrade that sends an Origin without its token, so no page, on this site or another, opens one; a client that sends no Origin, such as curl, can, and reads which modules changed. Omit sockets and it takes none. A checked upgrade is proxied to sockets.backend; a half closing normally ends the other half, and only an error destroys. A client that gives up while the issuer is deciding is not proxied at all. A socket error is reported through onError and never crashes the server.
  • reserveLoopbackPort() claims a free port before anything that must know its own origin up front.

The edge's types import node:http types, so a TypeScript consumer needs @types/node.

Two optional test hooks help exercise integrations:

  • cimdTransport(input, init) replaces outbound Client ID Metadata Document retrieval and returns a Response or Promise<Response>. Its arguments match fetch. Use it to serve fixture metadata for HTTPS client IDs without an external server. When omitted, the issuer uses its secure metadata transport.
  • onRequest({ method, url }) observes actual incoming HTTP requests at the issuer listener, such as discovery, JWKS, dynamic client registration, and token requests. Provisioning is in-process, so the observer sees only the test's own traffic. url is a URL; headers and bodies are never passed. The callback runs synchronously before handling each request. A thrown error makes that request fail with HTTP 500, so keep observers nonthrowing.

A fake issuer for tests

A test that needs only JWKS and key lists — a token that must expire in two seconds, a key granted on someone else's resource, an outage — wants the SDK's fake issuer, @gjermundgaraba/clankerauth-sdk/testing, instead of this package. Use startDisposableIssuer when the protocol itself is what the test is about — sign-in, consent, forward auth, dynamic registration.

MIT licensed. The bundled third-party licenses are listed in dist/THIRD_PARTY_NOTICES.txt.

版本与发布记录

@gjermundgaraba/clankerauth-dev 共发布 45 个版本,首次发布于 2026/09/20;过去 12 个月发布了 45 个版本。最新版本附带 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-dev 的常见问题

@gjermundgaraba/clankerauth-dev 是什么?

Disposable local clankerauth issuer for application development

如何安装 @gjermundgaraba/clankerauth-dev?

在项目目录运行 npm install @gjermundgaraba/clankerauth-dev,或使用 pnpm add / yarn add / bun add。

@gjermundgaraba/clankerauth-dev 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gjermundgaraba/clankerauth-dev 支持 ESM 还是 CommonJS?

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

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

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

@gjermundgaraba/clankerauth-dev 可以商用吗?

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

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

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

@gjermundgaraba/clankerauth-dev 还在维护吗?

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