@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, neverfetch:fetchownsSec-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, plusx-forwarded-proto,-hostand-uri. - It has a timeout (5 s by default) and rejects rather than deciding when the issuer is unreachable, too slow, or answers
204with noAuthorizationto forward.middlewareturns a rejection into a 502 and passes the error toonError; an empty credential is never forwarded upstream. - A refusal is relayed as the issuer wrote it: its status, its
Location, itsWWW-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. publicPathsdefaults to/mcp,/.well-knownand/healthz, and a request that already carries anAuthorizationheader is not checked whereverifiesAuthorization(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 answersfalsefor the paths Vite serves; otherwise anyAuthorizationvalue, evenx, reaches its pages and modules. Where it answersfalse, 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.tsinto a page the check never saw. Withsocketsgiven, an upgrade on such a path is refused with 400. upgradeonly takes the paths insockets.paths, so a development server keeps its own hot-reload socket; it returnsfalsefor 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 anOriginwithout its token, so no page, on this site or another, opens one; a client that sends noOrigin, such ascurl, can, and reads which modules changed. Omitsocketsand it takes none. A checked upgrade is proxied tosockets.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 throughonErrorand 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 aResponseorPromise<Response>. Its arguments matchfetch. 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.urlis aURL; 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.