@gjermundgaraba/clankerauth-dev 0.5.0 → 0.5.1

package/README.md

@@ -30,6 +30,20 @@ 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.
 
+To develop an app behind forward auth, pass a `cookieDomain`:
+
+```ts
+const issuer = await startDisposableIssuer({
+  resources: [{ identifier: "http://app.notes.localhost:8080/api", name: "Notes", scopes: [] }],
+  client: { name: "Notes console", redirect: "http://localhost:5173/callback", resources: [] },
+  cookieDomain: "notes.localhost",
+});
+
+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.
+
 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.

package/dist/index.d.ts

@@ -1,6 +1,13 @@
 export interface DisposableIssuerOptions {
   resources: Array<{ identifier: string; name: string; scopes: string[] }>;
   client: { name: string; redirect: string; resources: string[] };
+  /**
+   * Serve forward auth for apps under this domain, such as `notes.localhost`. The issuer is
+   * then `http://auth.<cookieDomain>:<port>` on the same loopback listener, and the forward
+   * cookie is shared with every host under the domain. Without it, the issuer is
+   * `http://127.0.0.1:<port>` and the forward-auth routes are not served.
+   */
+  cookieDomain?: string;
   /** 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. */