@gjermundgaraba/clankerauth-dev 0.5.1 → 0.6.0

package/README.md

@@ -30,6 +30,33 @@ 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.
 
+## Provisioning
+
+The issuer provisions what a test or a development script would otherwise script by hand against its HTTP API:
+
+```ts
+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` signs the owner in 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 workspace that survives a restart
+
+Pass `dataDir` and a fixed `port` to keep the issuer's state:
+
+```ts
+const issuer = await startDisposableIssuer({ ...options, dataDir: ".dev/auth", 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. 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`:
 
 ```ts
@@ -42,7 +69,38 @@ const issuer = await startDisposableIssuer({
 issuer.url; // http://auth.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`. Node's `fetch` always sends `Sec-Fetch-Mode: cors`, so a proxy written in Node must make the check with `node:http` to relay the browser's header. Without `cookieDomain` the issuer is `http://127.0.0.1:<port>` and these routes are not served.
+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.
+
+```ts
+import { forwardAuth, reserveLoopbackPort } from "@gjermundgaraba/clankerauth-dev/edge";
+
+export default defineConfig({
+  plugins: [
+    forwardAuth({
+      issuer: "http://auth.notes.localhost:5174",
+      appOrigin: "http://app.notes.localhost:5173",
+      resource: "http://app.notes.localhost:5173/",
+      backend: "http://127.0.0.1:8080",
+      socketPaths: ["/eventlog"],
+      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.
+- `publicPaths` defaults to `/mcp`, `/.well-known` and `/healthz`, and a request that already carries an `Authorization` header is never checked: agents onboard themselves and probes run.
+- `upgrade` only takes the paths in `socketPaths`, 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. A checked upgrade is proxied to `backend`; a half closing normally ends the other half, and only an error destroys. 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:
 

package/dist/THIRD_PARTY_NOTICES.txt

@@ -472,7 +472,7 @@ SOFTWARE.
 
 ---
 
-@gjermundgaraba/effect-actions@0.2.0
+@gjermundgaraba/effect-actions@0.3.0
 LICENSE
 MIT License
 

package/dist/edge.d.ts

@@ -0,0 +1,84 @@
+import type { IncomingHttpHeaders, IncomingMessage, Server, ServerResponse } from "node:http";
+import type { Duplex } from "node:stream";
+export interface CheckOptions {
+    /** The issuer origin serving `/forward-auth`, under the apps' shared cookie domain. */
+    readonly issuer: string;
+    /** The origin browsers reach this app at. Its host and scheme are forwarded. */
+    readonly appOrigin: string;
+    /**
+     * The resource identifier to ask for. One resource per app is a string; an app whose
+     * surfaces are separate resources passes a function of the request path.
+     */
+    readonly resource: string | ((path: string) => string);
+    /** How long to wait for the issuer. Default 5000 ms. */
+    readonly timeoutMs?: number;
+}
+/** What the issuer decided about one request. */
+export interface Decision {
+    readonly status: number;
+    readonly authorization: string | undefined;
+    readonly location: string | undefined;
+}
+/** The request fields a check reads. A Node `IncomingMessage` already is one. */
+export interface CheckedRequest {
+    readonly url?: string | undefined;
+    readonly headers: IncomingHttpHeaders;
+}
+/**
+ * Ask the issuer whether one request may proceed. Rejects instead of deciding when the
+ * issuer is unreachable, too slow, or answers `204` without the credential to forward:
+ * those are a broken edge, not a refusal to show a browser.
+ */
+export declare const check: (options: CheckOptions) => (request: CheckedRequest) => Promise<Decision>;
+export interface EdgeOptions extends CheckOptions {
+    /**
+     * Path prefixes answered without a check, because their callers bring their own
+     * credential or must work without one. Defaults to `/mcp`, `/.well-known`, `/healthz`.
+     */
+    readonly publicPaths?: readonly string[];
+    /** Where a checked upgrade is proxied, such as `http://127.0.0.1:8080`. */
+    readonly backend?: string;
+    /**
+     * Paths whose upgrades this edge owns. Everything else, including a development
+     * server's own hot-reload socket, is left untouched. Defaults to none.
+     */
+    readonly socketPaths?: readonly string[];
+    /** Called with anything this edge swallowed, so a dev server can print it. */
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * Connect-style middleware: an unauthenticated navigation is redirected through the
+ * issuer and back, anything else is refused in place, and a request that already
+ * carries a credential passes straight through.
+ */
+export declare const middleware: (options: EdgeOptions) => (request: CheckedRequest, response: ServerResponse, next: () => void) => void;
+/**
+ * Handle one `upgrade`. Returns `false` for a path this edge does not own, so a
+ * development server keeps its own hot-reload socket. An upgrade is never a
+ * navigation, so an unauthenticated one is refused in place: the page signs in and
+ * the client reconnects.
+ */
+export declare const upgrade: (options: EdgeOptions) => (request: IncomingMessage, socket: Duplex, head: Buffer) => boolean;
+/** Install both halves on a plain Node server, for an edge that is not a Vite plugin. */
+export declare const attach: (server: Server, options: EdgeOptions) => (request: CheckedRequest, response: ServerResponse, next: () => void) => void;
+/** The development server this plugin attaches to. Structural, so Vite is never imported. */
+export interface DevServerLike {
+    readonly middlewares: {
+        use(handler: (request: IncomingMessage, response: ServerResponse, next: () => void) => void): void;
+    };
+    readonly httpServer?: {
+        on(event: "upgrade", listener: (request: IncomingMessage, socket: Duplex, head: Buffer) => void): void;
+    } | null | undefined;
+}
+/**
+ * A Vite plugin applying the same edge. Nothing here imports Vite: the object is
+ * structurally what Vite accepts, so this package never puts Vite in a consumer's
+ * dependency graph or its type graph.
+ */
+export declare const forwardAuth: (options: EdgeOptions) => {
+    name: string;
+    apply: "serve";
+    configureServer: (server: DevServerLike) => void;
+};
+/** Claim a free loopback port before anything that must know its own origin up front. */
+export declare const reserveLoopbackPort: () => Promise<number>;

package/dist/edge.mjs

@@ -0,0 +1,2 @@
+import{createServer as e,request as t}from"node:http";const n=[`/mcp`,`/.well-known`,`/healthz`],r=e=>typeof e==`function`,i=e=>{let t=e.search(/[?#]/u);return t===-1?e:e.slice(0,t)},a=e=>e===void 0?``:Array.isArray(e)?e.join(`, `):String(e),o=e=>{let n=new URL(e.appOrigin),o=e.timeoutMs??5e3,s=t=>r(e.resource)?e.resource(t):e.resource;return r=>new Promise((c,l)=>{let u=r.url??`/`,d=new URL(`/forward-auth`,e.issuer);d.searchParams.set(`resource`,s(i(u)));let f=t(d,{headers:{cookie:a(r.headers.cookie),"sec-fetch-mode":a(r.headers[`sec-fetch-mode`]),"x-forwarded-proto":n.protocol.slice(0,-1),"x-forwarded-host":n.host,"x-forwarded-uri":u}},e=>{e.resume();let t=e.statusCode??502,{authorization:n,location:r}=e.headers;if(t===204&&n===void 0){l(/* @__PURE__ */ Error(`Forward auth answered 204 without an Authorization header to forward`));return}c({status:t,authorization:n,location:r})});f.setTimeout(o,()=>{f.destroy(/* @__PURE__ */ Error(`Forward auth did not answer within ${o}ms`))}),f.on(`error`,l),f.end()})},s=(e,t)=>t.some(t=>e===t||e.startsWith(`${t}/`)),c=e=>e instanceof Error?e:Error(String(e)),l=e=>{let t=o(e),r=e.publicPaths??[...n];return(n,a,o)=>{let l=i(n.url??`/`);if(n.headers.authorization!==void 0||s(l,r)){o();return}t(n).then(e=>{if(e.status===204){n.headers.authorization=e.authorization,o();return}a.writeHead(e.status,e.location===void 0?{}:{location:e.location}),a.end()},t=>{let n=c(t);e.onError?.(n),a.writeHead(502,{"content-type":`text/plain`}),a.end(n.message)})}},u=e=>Object.fromEntries(Object.entries(e).flatMap(([e,t])=>t===void 0?[]:[[e,Array.isArray(t)?t.join(`, `):t]])),d=e=>{let n=o(e);return(r,a,o)=>{let l=i(r.url??`/`);if(e.backend===void 0||!s(l,e.socketPaths??[]))return!1;let d=new URL(e.backend),f=(t,n,r)=>{r&&e.onError?.(r),a.end(`HTTP/1.1 ${t} ${n}\r\nConnection: close\r\n\r\n`)};a.on(`error`,t=>{e.onError?.(t),a.destroy()});let p=n=>{let i=t({hostname:d.hostname,port:d.port,path:r.url??`/`,headers:{...u(r.headers),authorization:n}});i.on(`upgrade`,(t,n,r)=>{let i=`HTTP/1.1 101 Switching Protocols\r
+`;for(let e=0;e<t.rawHeaders.length;e+=2)i+=`${t.rawHeaders[e]}: ${t.rawHeaders[e+1]}\r\n`;a.write(`${i}\r\n`),r.length&&a.write(r),o.length&&n.write(o),n.on(`error`,t=>{e.onError?.(t),a.destroy()}),a.once(`close`,()=>n.end()),n.once(`close`,()=>a.end()),a.pipe(n),n.pipe(a)}),i.on(`response`,e=>{e.resume(),f(e.statusCode??502,`Upgrade refused`)}),i.on(`error`,e=>f(502,`Bad Gateway`,e)),i.end()};return n(r).then(e=>{if(e.status!==204||e.authorization===void 0){f(401,`Unauthorized`);return}p(e.authorization)},e=>f(502,`Bad Gateway`,c(e))),!0}},f=(e,t)=>{let n=l(t),r=d(t);return e.on(`upgrade`,(e,t,n)=>{r(e,t,n)}),n},p=e=>{let t=l(e),n=d(e);return{name:`clankerauth-forward-auth`,apply:`serve`,configureServer:e=>{e.middlewares.use(t),e.httpServer?.on(`upgrade`,(e,t,r)=>{n(e,t,r)})}}},m=async()=>{let t=e();await new Promise(e=>t.listen(0,`127.0.0.1`,e));let n=t.address();if(!(n instanceof Object))throw Error(`Could not reserve a loopback port`);return await new Promise((e,n)=>t.close(t=>t?n(t):e())),n.port};export{f as attach,o as check,p as forwardAuth,l as middleware,m as reserveLoopbackPort,d as upgrade};

package/dist/index.d.ts

@@ -8,22 +8,63 @@ export interface DisposableIssuerOptions {
    * `http://127.0.0.1:<port>` and the forward-auth routes are not served.
    */
   cookieDomain?: string;
+  /**
+   * Keep the issuer's state in this directory instead of a temporary one: the owner
+   * account and password, the signing secret, the registered client and the database
+   * survive `close()` and the next start. Provisioning is idempotent, so the same
+   * resources and client are reused. The directory is never deleted. Treat it as the
+   * whole secret of the workspace, and keep it out of version control.
+   */
+  dataDir?: string;
+  /**
+   * Listen on this port instead of a random one. A persistent workspace needs a fixed
+   * one, because the origin is what browser storage, cookies and registered redirect
+   * URIs are keyed by. Default `0`.
+   */
+  port?: number;
   /** Test hook replacing outbound CIMD metadata retrieval. Defaults to the secure transport. */
   cimdTransport?: (input: RequestInfo | URL, init?: RequestInit) => Response | Promise<Response>;
   /** Test hook observing incoming HTTP requests, including provisioning. No headers or bodies. */
   onRequest?: (request: { method: string; url: URL }) => void;
 }
 
+/** What a persistent workspace keeps between runs. Written by this package only. */
+export interface Identity {
+  email: string;
+  password: string;
+  secret: string;
+  clientId?: string;
+  clientSecret?: string;
+}
+
+/** A browser-equivalent owner session: the forward cookie, as a header and as pairs. */
+export interface OwnerSession {
+  cookie: string;
+  cookies: Array<{ name: string; value: string }>;
+}
+
 export interface DisposableIssuer {
   issuer: string;
   clientId: string;
   clientSecret: string;
   owner: { email: string; password: string };
   url: string;
+  /** The port the issuer listens on, which is also the apps' port under a cookie domain. */
+  port: number;
   directory: string;
-  /** Drain requests, close SQLite, and remove all temporary identity state. Idempotent. */
+  /** Mint a scoped API key and return its secret. Permissions are resource identifier to scopes. */
+  apiKey(options: { name?: string; permissions: Record<string, string[]> }): Promise<string>;
+  /**
+   * Sign the owner in and seal the forward cookie for `appOrigin`, exactly as a browser
+   * does through `/forward-auth/continue`. Needs `cookieDomain`. The `cookies` array is
+   * what a browser automation harness adds to a context.
+   */
+  ownerSession(appOrigin: string): Promise<OwnerSession>;
+  /** An access token for one resource, obtained through the same forward-auth check. */
+  ownerToken(options: { resource: string; appOrigin: string }): Promise<string>;
+  /** Drain requests and close SQLite. Removes the directory only when it is temporary. Idempotent. */
   close(): Promise<void>;
 }
 
-/** Start a fresh issuer on a random loopback port. The caller owns signals and must await close(). */
+/** Start an issuer on a loopback port. The caller owns signals and must await close(). */
 export function startDisposableIssuer(options: DisposableIssuerOptions): Promise<DisposableIssuer>;