@corespec/vite-plugin-api-auto-login 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,254 @@
-# Temporary Holding Version
+# @corespec/vite-plugin-api-auto-login
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@corespec/vite-plugin-api-auto-login)](https://www.npmjs.com/package/@corespec/vite-plugin-api-auto-login)
+[![CI](https://github.com/core-spec-tech/vite-plugin-api-auto-login/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/core-spec-tech/vite-plugin-api-auto-login/actions/workflows/ci.yml)
+[![Security checks](https://github.com/core-spec-tech/vite-plugin-api-auto-login/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/core-spec-tech/vite-plugin-api-auto-login/actions/workflows/security.yml)
+[![License](https://img.shields.io/npm/l/@corespec/vite-plugin-api-auto-login)](https://www.npmjs.com/package/@corespec/vite-plugin-api-auto-login)
+[![Vite compatibility](https://registry.vite.dev/api/badges?package=%40corespec%2Fvite-plugin-api-auto-login&tool=vite)](https://registry.vite.dev/)
+[![Rollup compatibility](https://registry.vite.dev/api/badges?package=%40corespec%2Fvite-plugin-api-auto-login&tool=rollup)](https://registry.vite.dev/)
+
+A reusable Vite plugin that automatically logs in to an API from the Node.js development server.
+
+## Installation
+
+```bash
+npm install -D @corespec/vite-plugin-api-auto-login
+```
+
+## Usage
+
+Add the plugin to your Vite configuration:
+
+```ts
+import { defineConfig } from 'vite'
+import { viteAPIAutoLogin } from '@corespec/vite-plugin-api-auto-login'
+
+export default defineConfig({
+  plugins: [viteAPIAutoLogin()],
+})
+```
+
+The plugin runs only in Vite's development server. It reads environment variables prefixed with `API_AUTO_LOGIN_` and injects an authentication cookie into responses to matching HTML document requests.
+
+## Customizing form field names
+
+Use `formFields` to rename either credential field without writing a strategy:
+
+```ts
+viteAPIAutoLogin({
+  formFields: { username: 'email' },
+})
+```
+
+The default names are `username` and `password`. For example,
+`formFields: { username: 'login', password: 'passcode' }` changes both.
+Values still come from `API_AUTO_LOGIN_USERNAME` and `API_AUTO_LOGIN_PASSWORD`;
+only the outgoing form field names change. Names must be non-empty and distinct.
+The `User-Agent` header is unaffected.
+
+Use `formFields` only with the default strategy; it cannot be combined with
+`request` or `createAuthRequest`. When constructing the exported strategy directly,
+use `new FormDataAuthRequest(config, { username: 'email' })`.
+The `FormFieldNames` type is exported for reusable mappings.
+
+## Customizing the login request
+
+Use `createAuthRequest(config)` to create a `AuthRequest` strategy for each
+Vite server initialization. The strategy controls the URL, HTTP method, headers,
+and body. A class can keep any additional configuration it needs:
+
+```ts
+import { defineConfig } from 'vite'
+import {
+  viteAPIAutoLogin,
+  type PluginEnv,
+  type AuthRequest,
+  type AuthRequestOptions,
+} from '@corespec/vite-plugin-api-auto-login'
+
+class JsonAuthRequest implements AuthRequest {
+  create(config: Readonly<PluginEnv>): AuthRequestOptions {
+    if (!config.loginUrl || !config.username || !config.password) {
+      throw new Error('JSON login requires an endpoint, username, and password')
+    }
+
+    return {
+      url: config.loginUrl,
+      init: {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          username: config.username,
+          password: config.password,
+        }),
+      },
+    }
+  }
+}
+
+export default defineConfig({
+  plugins: [viteAPIAutoLogin({ createAuthRequest: () => new JsonAuthRequest() })],
+})
+```
+
+The factory receives the readonly parsed configuration and runs once per
+`configureServer` invocation, not once per request. Return a fresh instance to
+keep mutable strategy state separate between servers. Factory errors are logged
+and prevent middleware registration for that server. The factory is synchronous.
+
+Use `request: new JsonAuthRequest()` for
+shared strategy instances. Supply either `request` or `createAuthRequest`, never
+both; TypeScript and runtime validation enforce this.
+
+`create` can return a promise. It runs whenever a new token is needed, so create
+a fresh body for each call. Concurrent login requests are deduplicated, and
+valid JWT tokens are cached until their `exp` timestamp. Tokens without a
+readable JWT expiry are not cached.
+
+Without this option, `FormDataAuthRequest` sends a multipart POST
+with `username` and `password` fields and a `User-Agent` header. This class is also exported
+for consumers that want to extend the default request.
+
+The `init` object supports Undici fetch options, including `signal` and
+`redirect`. The plugin manages `dispatcher` through its TLS configuration.
+The response must still be successful HTTP JSON containing a non-empty
+`token` string. Custom strategies validate their own authentication requirements and can omit
+all three default login variables.
+
+## Environment variables
+
+Define these variables in your Vite environment files, such as `.env.local`, `.env.development`, or another file in `envDir` that Vite loads for the current mode.
+
+Required by the default `FormDataAuthRequest` strategy only:
+
+| Variable                   | Description                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| `API_AUTO_LOGIN_LOGIN_URL` | Login endpoint URL used to request an authentication token.                                  |
+| `API_AUTO_LOGIN_USERNAME`  | Account username sent to the login endpoint; may be an email address if the API supports it. |
+| `API_AUTO_LOGIN_PASSWORD`  | Account password sent to the login endpoint.                                                 |
+
+Optional variables:
+
+| Variable                            | Default           | Description                                                                   |
+| ----------------------------------- | ----------------- | ----------------------------------------------------------------------------- |
+| `API_AUTO_LOGIN_COOKIE_NAME`        | `your_token_name` | Name of the cookie added to the response with the authentication token.       |
+| `API_AUTO_LOGIN_USER_AGENT`         | `vite`            | Value sent in the login request's `User-Agent` HTTP header.                   |
+| `API_AUTO_LOGIN_ALLOW_INSECURE_TLS` | `false`           | Set to `true` to disable TLS certificate verification for the login endpoint. |
+
+## Configuration parsing
+
+`PluginConfig.fromEnv(env)` converts the environment values returned by Vite's
+`loadEnv` into readonly configuration properties. It applies the shared defaults
+and parses the TLS flag. Use this named factory instead of constructing
+`PluginConfig` directly.
+
+Login URL, username, and password are optional in the shared configuration.
+`FormDataAuthRequest` validates them when the plugin creates the default
+strategy and whenever it builds a request. A custom strategy or factory is
+responsible for validating the fields it uses.
+
+The login variables deliberately avoid the `VITE_` prefix so they remain on the server with Vite's default configuration. Do not add `API_AUTO_LOGIN_` to Vite's `envPrefix`, as this would expose credentials to client code.
+
+## Vue + MSW example
+
+Run `npm ci` and `npm run example` from this repository, then open
+[http://127.0.0.1:5173](http://127.0.0.1:5173).
+
+The [example guide](examples/vue-msw/README.md) explains the mock API, cookie
+flow, and `formFields: { username: 'email' }` mapping. No external API or real
+credentials are needed.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for code conventions, design guidelines,
+and the required checks.
+
+Use the Node.js version pinned in `.nvmrc`. GitHub CI and publishing use the same
+file. With nvm installed:
+
+```bash
+nvm install
+nvm use
+npm ci
+npm run check
+npm run build
+```
+
+`npm run check` runs formatting checks, linting, the full project type check, and all tests once.
+Use `npm test` for watch mode or `npm run coverage` for a coverage report.
+The build produces ESM, CommonJS, and TypeScript declarations.
+Use `npm run format` to format files with Prettier (100-character print width).
+
+Tests are grouped under `tests/auth`, `tests/config`, and `tests/http`.
+`tests/plugin.spec.ts` covers plugin integration, with shared HTTP fixtures in
+`tests/helpers`. Editor formatting defaults are defined in `.editorconfig`.
+Local environment overrides (`.env.local` and `.env.*.local`) are ignored by Git.
+
+### Source imports
+
+Use `@/` for imports from `src/`, including imports in tests:
+
+```ts
+import { PluginConfig } from '@/config/PluginConfig'
+```
+
+TypeScript and Vite/Vitest resolve this alias locally. The declaration build
+uses `tsc-alias` to replace aliases with relative paths in published types;
+consumers do not need to configure `@/`. Imports between test helpers stay relative.
+
+## Local linking
+
+When developing this package alongside a consuming Vite application, run the linking commands from each repository's root directory:
+
+```bash
+cd vite-plugin-api-auto-login
+npm link
+
+cd ../your-app
+npm link @corespec/vite-plugin-api-auto-login
+```
+
+## Security scanning
+
+GitHub Actions runs CodeQL for TypeScript and workflow code, dependency review
+on pull requests, and scheduled npm audits. Run `npm run security:audit` locally;
+high and critical dependency findings also block publishing.
+See [security setup](CONTRIBUTING.md#security-checks) for thresholds and the GitHub
+settings needed for secret scanning and merge protection.
+
+## Publishing
+
+The `.github/workflows/publish.yml` workflow stages releases for approval when a version tag (`v*`) or package-specific tag (`@corespec/vite-plugin-api-auto-login@*`) is pushed. The tag must match the version in `package.json`. The workflow runs linting, type checking, tests, and the build before staging the package on npm. A maintainer approves the staged version with 2FA to publish it.
+
+The initial version is `0.1.0`. Releases use Semantic Versioning and Conventional
+Commits; see [CONTRIBUTING.md](CONTRIBUTING.md#versioning-and-releases) for the
+release commands and the `0.x` versioning policy.
+
+Release setup:
+
+1. Store a granular npm publishing token with access to the `@corespec` scope
+   as the repository Actions secret `NPM_TOKEN`. Use a stage-only token; CI does
+   not need to bypass 2FA. Keep local tokens in an ignored `.env` file.
+2. Run `npm ci`, `npm run check`, and `npm run example:build`.
+3. The renamed package's initial release uses the tag
+   `@corespec/vite-plugin-api-auto-login@0.1.0`, preserving the old package's
+   `v0.1.0` tag. For later releases, use `npm run release` or an explicit
+   bump command described in CONTRIBUTING.md.
+4. Push the release commit and tag with `git push --follow-tags`. The Publish
+   workflow checks, builds, and stages the package with provenance. The npm
+   token is available only to its staging step.
+5. Review the version in npm's Staged Packages tab and approve it with 2FA,
+   or run `npm stage approve <stage-id>` while logged in as a maintainer.
+   A successful staging workflow does not mean the version is publicly available.
+
+To retry an existing tag, manually run the Publish workflow and supply that tag
+(for example `v0.1.0`). It checks out the tagged source and verifies the version.
+
+Trusted publishing can replace the token after configuring owner `core-spec-tech`,
+repository `vite-plugin-api-auto-login`, and workflow `publish.yml` in npm's package
+settings. Then remove `NODE_AUTH_TOKEN` from the staging step and delete
+the repository secret.
+
+GitHub CI runs on pushes and pull requests. You can configure Renovate through its GitHub app using `renovate.json`.
+
+See [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) for details.

package/dist/auth/AuthRequest.d.ts

@@ -0,0 +1,10 @@
+import type { RequestInit } from 'undici';
+import type { PluginEnv } from '../config/types.js';
+export type AuthRequestOptions = {
+    url: string | URL;
+    init: Omit<RequestInit, 'dispatcher'>;
+};
+export interface AuthRequest {
+    create(config: Readonly<PluginEnv>): AuthRequestOptions | Promise<AuthRequestOptions>;
+}
+//# sourceMappingURL=AuthRequest.d.ts.map

package/dist/auth/AuthRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthRequest.d.ts","sourceRoot":"","sources":["../../src/auth/AuthRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAEzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;IACjB,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;CACtC,CAAA;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;CACtF"}

package/dist/auth/AuthSession.d.ts

@@ -0,0 +1,24 @@
+import { fetch as undiciFetch } from 'undici';
+import type { Dispatcher } from 'undici';
+import type { PluginEnv } from '../config/types.js';
+import type { AuthRequest } from './AuthRequest.js';
+type FetchLike = typeof undiciFetch;
+type AuthSessionDependencies = {
+    request?: AuthRequest;
+    createDispatcher?: () => Dispatcher;
+    fetch?: FetchLike;
+};
+export declare class AuthSession {
+    private readonly env;
+    private readonly request;
+    private readonly fetchImpl;
+    private readonly dispatcher;
+    private cachedToken;
+    private pendingLogin;
+    constructor(env: PluginEnv, dependencies?: AuthSessionDependencies);
+    getToken(): Promise<string>;
+    private requestToken;
+    private parseJwtExpiry;
+}
+export {};
+//# sourceMappingURL=AuthSession.d.ts.map

package/dist/auth/AuthSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthSession.d.ts","sourceRoot":"","sources":["../../src/auth/AuthSession.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,IAAI,WAAW,EAAE,MAAM,QAAQ,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AAExC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAOrD,KAAK,SAAS,GAAG,OAAO,WAAW,CAAA;AAEnC,KAAK,uBAAuB,GAAG;IAC7B,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,gBAAgB,CAAC,EAAE,MAAM,UAAU,CAAA;IACnC,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB,CAAA;AAED,qBAAa,WAAW;IAQpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,YAAY,CAA6B;gBAG9B,GAAG,EAAE,SAAS,EAC/B,YAAY,GAAE,uBAA4B;IAUtC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;YAiBnB,YAAY;IAuB1B,OAAO,CAAC,cAAc;CASvB"}

package/dist/auth/FormDataAuthRequest.d.ts

@@ -0,0 +1,9 @@
+import type { FormFieldNames, PluginEnv } from '../config/types.js';
+import type { AuthRequest, AuthRequestOptions } from './AuthRequest.js';
+export declare class FormDataAuthRequest implements AuthRequest {
+    private readonly fields;
+    constructor(config?: Readonly<PluginEnv>, fields?: Readonly<FormFieldNames>);
+    create(config: Readonly<PluginEnv>): AuthRequestOptions;
+    private validate;
+}
+//# sourceMappingURL=FormDataAuthRequest.d.ts.map

package/dist/auth/FormDataAuthRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormDataAuthRequest.d.ts","sourceRoot":"","sources":["../../src/auth/FormDataAuthRequest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAEzE,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,MAAM,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAE,QAAQ,CAAC,cAAc,CAAM;IAkB/E,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,kBAAkB;IAgBvD,OAAO,CAAC,QAAQ;CASjB"}

package/dist/config/PluginConfig.d.ts

@@ -0,0 +1,14 @@
+import type { PluginEnv, PluginEnvInput } from './types.js';
+export declare const DEFAULT_COOKIE_NAME = "your_token_name";
+export declare const DEFAULT_USER_AGENT = "vite";
+export declare class PluginConfig implements PluginEnv {
+    readonly allowInsecureTls: boolean;
+    readonly cookieName: string;
+    readonly username: string | undefined;
+    readonly loginUrl: string | undefined;
+    readonly password: string | undefined;
+    readonly userAgent: string;
+    static fromEnv(env: PluginEnvInput): PluginConfig;
+    private constructor();
+}
+//# sourceMappingURL=PluginConfig.d.ts.map

package/dist/config/PluginConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginConfig.d.ts","sourceRoot":"","sources":["../../src/config/PluginConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/D,eAAO,MAAM,mBAAmB,oBAAoB,CAAA;AACpD,eAAO,MAAM,kBAAkB,SAAS,CAAA;AAExC,qBAAa,YAAa,YAAW,SAAS;IAC5C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAE1B,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,YAAY;IAIjD,OAAO;CAQR"}

package/dist/config/types.d.ts

@@ -0,0 +1,29 @@
+import type { AuthRequest } from '../auth/AuthRequest.js';
+export type PluginEnv = {
+    allowInsecureTls: boolean;
+    cookieName: string;
+    username?: string;
+    loginUrl?: string;
+    password?: string;
+    userAgent: string;
+};
+export type PluginEnvInput = Readonly<Record<string, string | undefined>>;
+export type AuthRequestFactory = (config: Readonly<PluginEnv>) => AuthRequest;
+export type FormFieldNames = {
+    username?: string;
+    password?: string;
+};
+export type AutoLoginOptions = {
+    formFields?: FormFieldNames;
+    request?: never;
+    createAuthRequest?: never;
+} | {
+    formFields?: never;
+    request: AuthRequest;
+    createAuthRequest?: never;
+} | {
+    formFields?: never;
+    request?: never;
+    createAuthRequest: AuthRequestFactory;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/config/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD,MAAM,MAAM,SAAS,GAAG;IACtB,gBAAgB,EAAE,OAAO,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;AAEzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,WAAW,CAAA;AAE7E,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,UAAU,CAAC,EAAE,cAAc,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAAC,iBAAiB,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3E;IAAE,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC;IAAC,iBAAiB,CAAC,EAAE,KAAK,CAAA;CAAE,GACvE;IAAE,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAAC,iBAAiB,EAAE,kBAAkB,CAAA;CAAE,CAAA"}

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const PLUGIN_NAME = "vite-plugin-api-auto-login";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,+BAA+B,CAAA"}

package/dist/http/AuthResponse.d.ts

@@ -0,0 +1,7 @@
+import type { ServerResponse } from 'node:http';
+export declare class AuthResponse {
+    private readonly response;
+    constructor(response: ServerResponse);
+    setAuthCookie(cookieName: string, token: string): void;
+}
+//# sourceMappingURL=AuthResponse.d.ts.map

package/dist/http/AuthResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthResponse.d.ts","sourceRoot":"","sources":["../../src/http/AuthResponse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE/C,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,cAAc;IAErD,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAkBvD"}

package/dist/http/HtmlDocumentRequest.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage } from 'node:http';
+export declare class HtmlDocumentRequest {
+    static matches(req: IncomingMessage): boolean;
+}
+//# sourceMappingURL=HtmlDocumentRequest.d.ts.map

package/dist/http/HtmlDocumentRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HtmlDocumentRequest.d.ts","sourceRoot":"","sources":["../../src/http/HtmlDocumentRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAIhD,qBAAa,mBAAmB;IAC9B,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO;CAW9C"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { viteAPIAutoLogin } from './plugin.js';
+export { FormDataAuthRequest } from './auth/FormDataAuthRequest.js';
+export type { AuthRequest, AuthRequestOptions } from './auth/AuthRequest.js';
+export type { AutoLoginOptions, PluginEnv, AuthRequestFactory, FormFieldNames, } from './config/types.js';
+export { PluginConfig } from './config/PluginConfig.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACzE,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/middleware/AutoLoginMiddleware.d.ts

@@ -0,0 +1,12 @@
+import type { Connect, Logger } from 'vite';
+import type { AuthRequest } from '../auth/AuthRequest.js';
+import type { PluginEnv } from '../config/types.js';
+export declare class AutoLoginMiddleware {
+    private readonly config;
+    private readonly logger;
+    private readonly request;
+    private session;
+    constructor(config: PluginEnv, logger: Pick<Logger, 'error'>, request: AuthRequest);
+    readonly handle: Connect.NextHandleFunction;
+}
+//# sourceMappingURL=AutoLoginMiddleware.d.ts.map

package/dist/middleware/AutoLoginMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutoLoginMiddleware.d.ts","sourceRoot":"","sources":["../../src/middleware/AutoLoginMiddleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAG3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAK/C,qBAAa,mBAAmB;IAI5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,OAAO,CAAyB;gBAGrB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,WAAW;IAGvC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAiB1C;CACF"}

package/dist/plugin.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from 'vite';
+import type { AutoLoginOptions } from './config/types.js';
+export declare function viteAPIAutoLogin(options?: AutoLoginOptions): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAMlC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGtD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAoCvE"}

package/dist/vite-plugin-api-auto-login.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("vite"),t=require("undici"),n=require("jose");var r=class{fields;constructor(e,t={}){if(this.fields={username:t.username??`username`,password:t.password??`password`},!this.fields.username.trim()||!this.fields.password.trim()||this.fields.username===this.fields.password)throw Error(`Form field names must be non-empty and distinct`);e&&this.validate(e)}create(e){let{username:n,password:r,loginUrl:i}=this.validate(e),a=new t.FormData;return a.set(this.fields.username,n),a.set(this.fields.password,r),{url:i,init:{method:`POST`,headers:{"User-Agent":e.userAgent},body:a}}}validate(e){let{loginUrl:t,username:n,password:r}=e;if(!t||!n||!r)throw Error(`Missing required env vars: API_AUTO_LOGIN_LOGIN_URL, API_AUTO_LOGIN_USERNAME, API_AUTO_LOGIN_PASSWORD`);return{loginUrl:t,username:n,password:r}}},i=`vite-plugin-api-auto-login`,a=class e{allowInsecureTls;cookieName;username;loginUrl;password;userAgent;static fromEnv(t){return new e(t)}constructor(e){this.allowInsecureTls=e.API_AUTO_LOGIN_ALLOW_INSECURE_TLS===`true`,this.cookieName=e.API_AUTO_LOGIN_COOKIE_NAME??`your_token_name`,this.username=e.API_AUTO_LOGIN_USERNAME,this.loginUrl=e.API_AUTO_LOGIN_LOGIN_URL,this.password=e.API_AUTO_LOGIN_PASSWORD,this.userAgent=e.API_AUTO_LOGIN_USER_AGENT??`vite`}},o=class{env;request;fetchImpl;dispatcher;cachedToken;pendingLogin;constructor(e,n={}){this.env=e,this.request=n.request??new r,this.fetchImpl=n.fetch??t.fetch,e.allowInsecureTls&&(this.dispatcher=n.createDispatcher?.()??new t.Agent({connect:{rejectUnauthorized:!1}}))}async getToken(){return this.cachedToken?.expiresAt!==void 0&&this.cachedToken.expiresAt>Date.now()?this.cachedToken.value:(this.pendingLogin??=this.requestToken().then(e=>(this.cachedToken=e,e.value)).finally(()=>{this.pendingLogin=void 0}),this.pendingLogin)}async requestToken(){let{url:e,init:t}=await this.request.create(this.env),n=await this.fetchImpl(e,{...t,dispatcher:this.dispatcher});if(!n.ok)throw Error(`Login request failed with status ${n.status}`);let r=await n.json();if(typeof r.token!=`string`||r.token.length===0)throw Error(`Login response did not include a token`);return{expiresAt:this.parseJwtExpiry(r.token),value:r.token}}parseJwtExpiry(e){try{let{exp:t}=(0,n.decodeJwt)(e);return typeof t==`number`?t*1e3:void 0}catch{return}}},s=class{response;constructor(e){this.response=e}setAuthCookie(e,t){let n=`${e}=${t}; Path=/; SameSite=Lax`,r=this.response.getHeader(`Set-Cookie`);if(!r){this.response.setHeader(`Set-Cookie`,n);return}let i;i=Array.isArray(r)?r:[String(r)],this.response.setHeader(`Set-Cookie`,[...i,n])}},c=`text/html`,l=class{static matches(e){return e.headers.upgrade?.toLowerCase()===`websocket`||e.method!==`GET`&&e.method!==`HEAD`?!1:e.headers.accept?.includes(c)??!1}},u=class{config;logger;request;session;constructor(e,t,n){this.config=e,this.logger=t,this.request=n}handle=async(e,t,n)=>{if(!l.matches(e))n();else{try{this.session??=new o(this.config,{request:this.request});let e=await this.session.getToken();new s(t).setAuthCookie(this.config.cookieName,e)}catch(e){let t=e instanceof Error?e.message:String(e),n=this.config.loginUrl?` (${this.config.loginUrl})`:``;this.logger.error(`[${i}] ${t}${n}`)}n()}}};function d(t={}){if(t.request!==void 0&&t.createAuthRequest!==void 0)throw Error(`Use either request or createAuthRequest, not both`);if(t.formFields!==void 0&&(t.request!==void 0||t.createAuthRequest!==void 0))throw Error(`Use formFields only with the default request strategy`);return{name:i,apply:`serve`,configureServer(n){let{mode:o,envDir:s,logger:c}=n.config;try{let i=a.fromEnv((0,e.loadEnv)(o,s,`API_AUTO_LOGIN_`)),l=t.request;if(t.createAuthRequest?l=t.createAuthRequest(i):l||=new r(i,t.formFields),!l||typeof l.create!=`function`)throw Error(`Token request must provide a create method`);let d=new u(i,c,l);n.middlewares.use(d.handle)}catch(e){c.error(`[${i}] ${e instanceof Error?e.message:String(e)}`)}}}}exports.FormDataAuthRequest=r,exports.PluginConfig=a,exports.viteAPIAutoLogin=d;

package/dist/vite-plugin-api-auto-login.js

@@ -0,0 +1,144 @@
+import { loadEnv as e } from "vite";
+import { Agent as t, FormData as n, fetch as r } from "undici";
+import { decodeJwt as i } from "jose";
+// src/auth/FormDataAuthRequest.ts
+var a = class {
+	fields;
+	constructor(e, t = {}) {
+		if (this.fields = {
+			username: t.username ?? "username",
+			password: t.password ?? "password"
+		}, !this.fields.username.trim() || !this.fields.password.trim() || this.fields.username === this.fields.password) throw Error("Form field names must be non-empty and distinct");
+		e && this.validate(e);
+	}
+	create(e) {
+		let { username: t, password: r, loginUrl: i } = this.validate(e), a = new n();
+		return a.set(this.fields.username, t), a.set(this.fields.password, r), {
+			url: i,
+			init: {
+				method: "POST",
+				headers: { "User-Agent": e.userAgent },
+				body: a
+			}
+		};
+	}
+	validate(e) {
+		let { loginUrl: t, username: n, password: r } = e;
+		if (!t || !n || !r) throw Error("Missing required env vars: API_AUTO_LOGIN_LOGIN_URL, API_AUTO_LOGIN_USERNAME, API_AUTO_LOGIN_PASSWORD");
+		return {
+			loginUrl: t,
+			username: n,
+			password: r
+		};
+	}
+}, o = "vite-plugin-api-auto-login", s = class e {
+	allowInsecureTls;
+	cookieName;
+	username;
+	loginUrl;
+	password;
+	userAgent;
+	static fromEnv(t) {
+		return new e(t);
+	}
+	constructor(e) {
+		this.allowInsecureTls = e.API_AUTO_LOGIN_ALLOW_INSECURE_TLS === "true", this.cookieName = e.API_AUTO_LOGIN_COOKIE_NAME ?? "your_token_name", this.username = e.API_AUTO_LOGIN_USERNAME, this.loginUrl = e.API_AUTO_LOGIN_LOGIN_URL, this.password = e.API_AUTO_LOGIN_PASSWORD, this.userAgent = e.API_AUTO_LOGIN_USER_AGENT ?? "vite";
+	}
+}, c = class {
+	env;
+	request;
+	fetchImpl;
+	dispatcher;
+	cachedToken;
+	pendingLogin;
+	constructor(e, n = {}) {
+		this.env = e, this.request = n.request ?? new a(), this.fetchImpl = n.fetch ?? r, e.allowInsecureTls && (this.dispatcher = n.createDispatcher?.() ?? new t({ connect: { rejectUnauthorized: !1 } }));
+	}
+	async getToken() {
+		return this.cachedToken?.expiresAt !== void 0 && this.cachedToken.expiresAt > Date.now() ? this.cachedToken.value : (this.pendingLogin ??= this.requestToken().then((e) => (this.cachedToken = e, e.value)).finally(() => {
+			this.pendingLogin = void 0;
+		}), this.pendingLogin);
+	}
+	async requestToken() {
+		let { url: e, init: t } = await this.request.create(this.env), n = await this.fetchImpl(e, {
+			...t,
+			dispatcher: this.dispatcher
+		});
+		if (!n.ok) throw Error(`Login request failed with status ${n.status}`);
+		let r = await n.json();
+		if (typeof r.token != "string" || r.token.length === 0) throw Error("Login response did not include a token");
+		return {
+			expiresAt: this.parseJwtExpiry(r.token),
+			value: r.token
+		};
+	}
+	parseJwtExpiry(e) {
+		try {
+			let { exp: t } = i(e);
+			return typeof t == "number" ? t * 1e3 : void 0;
+		} catch {
+			return;
+		}
+	}
+}, l = class {
+	response;
+	constructor(e) {
+		this.response = e;
+	}
+	setAuthCookie(e, t) {
+		let n = `${e}=${t}; Path=/; SameSite=Lax`, r = this.response.getHeader("Set-Cookie");
+		if (!r) {
+			this.response.setHeader("Set-Cookie", n);
+			return;
+		}
+		let i;
+		i = Array.isArray(r) ? r : [String(r)], this.response.setHeader("Set-Cookie", [...i, n]);
+	}
+}, u = "text/html", d = class {
+	static matches(e) {
+		return e.headers.upgrade?.toLowerCase() === "websocket" || e.method !== "GET" && e.method !== "HEAD" ? !1 : e.headers.accept?.includes(u) ?? !1;
+	}
+}, f = class {
+	config;
+	logger;
+	request;
+	session;
+	constructor(e, t, n) {
+		this.config = e, this.logger = t, this.request = n;
+	}
+	handle = async (e, t, n) => {
+		if (!d.matches(e)) n();
+		else {
+			try {
+				this.session ??= new c(this.config, { request: this.request });
+				let e = await this.session.getToken();
+				new l(t).setAuthCookie(this.config.cookieName, e);
+			} catch (e) {
+				let t = e instanceof Error ? e.message : String(e), n = this.config.loginUrl ? ` (${this.config.loginUrl})` : "";
+				this.logger.error(`[${o}] ${t}${n}`);
+			}
+			n();
+		}
+	};
+};
+// src/plugin.ts
+function p(t = {}) {
+	if (t.request !== void 0 && t.createAuthRequest !== void 0) throw Error("Use either request or createAuthRequest, not both");
+	if (t.formFields !== void 0 && (t.request !== void 0 || t.createAuthRequest !== void 0)) throw Error("Use formFields only with the default request strategy");
+	return {
+		name: o,
+		apply: "serve",
+		configureServer(n) {
+			let { mode: r, envDir: i, logger: c } = n.config;
+			try {
+				let o = s.fromEnv(e(r, i, "API_AUTO_LOGIN_")), l = t.request;
+				if (t.createAuthRequest ? l = t.createAuthRequest(o) : l ||= new a(o, t.formFields), !l || typeof l.create != "function") throw Error("Token request must provide a create method");
+				let u = new f(o, c, l);
+				n.middlewares.use(u.handle);
+			} catch (e) {
+				c.error(`[${o}] ${e instanceof Error ? e.message : String(e)}`);
+			}
+		}
+	};
+}
+export { a as FormDataAuthRequest, s as PluginConfig, p as viteAPIAutoLogin };

package/package.json

@@ -1,6 +1,113 @@
 {
   "name": "@corespec/vite-plugin-api-auto-login",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Reusable Vite plugin for API auto login during local development",
+  "type": "module",
+  "main": "./dist/vite-plugin-api-auto-login.cjs",
+  "module": "./dist/vite-plugin-api-auto-login.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/vite-plugin-api-auto-login.js",
+      "require": "./dist/vite-plugin-api-auto-login.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && npm run build:types",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly && tsc-alias -p tsconfig.build.json",
+    "test": "vitest",
+    "coverage": "vitest run --coverage",
+    "release": "commit-and-tag-version",
+    "lint:file:fix": "npm-run-all \"eslint -- {1} --fix\" --",
+    "lint:file": "npm-run-all \"eslint -- {1}\" --",
+    "eslint": "eslint",
+    "lint:fix": "eslint . --fix",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit && vue-tsc --noEmit -p examples/vue-msw/tsconfig.json",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test -- --run",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "example": "npm run build && node examples/vue-msw/dev.ts",
+    "example:build": "npm run build && vue-tsc --noEmit -p examples/vue-msw/tsconfig.json && vite build --config examples/vue-msw/vite.config.ts",
+    "release:first": "npm run release -- --first-release",
+    "release:patch": "npm run release -- --release-as patch",
+    "release:minor": "npm run release -- --release-as minor",
+    "release:major": "npm run release -- --release-as major",
+    "security:audit": "npm audit --package-lock-only --include=dev --audit-level=high"
+  },
+  "license": "ISC",
+  "engines": {
+    "node": ">=22.23.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@msw/serve": "^0.11.0",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/node": "^22.20.5",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "@vitest/coverage-v8": "^5.0.5",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "commit-and-tag-version": "^13.3.0",
+    "eslint": "^10.14.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-vue": "^10.12.0",
+    "globals": "^17.14.0",
+    "msw": "^3.0.4",
+    "npm-run-all2": "^9.0.4",
+    "prettier": "3.9.10",
+    "tsc-alias": "^1.9.10",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "vue": "^3.5.45",
+    "vue-tsc": "^3.3.14"
+  },
+  "dependencies": {
+    "jose": "^6.2.15",
+    "undici": "^8.12.3"
+  },
+  "peerDependencies": {
+    "vite": "^7.0.0 || ^8.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "vite-plugin",
+    "authentication",
+    "auto-login"
+  ],
+  "compatiblePackages": {
+    "schemaVersion": 1,
+    "vite": {
+      "type": "compatible",
+      "versions": "^7.0.0 || ^8.0.0",
+      "note": "Development server only; requires Vite configureServer and middleware APIs."
+    },
+    "rollup": {
+      "type": "incompatible",
+      "reason": "Requires the Vite development server and its configureServer hook."
+    },
+    "rolldown": {
+      "type": "incompatible",
+      "reason": "Requires the Vite development server and its configureServer hook."
+    }
+  },
+  "overrides": {
+    "minimatch@^10.0.0": "^11.0.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/core-spec-tech/vite-plugin-api-auto-login.git"
+  },
+  "homepage": "https://github.com/core-spec-tech/vite-plugin-api-auto-login#readme",
+  "bugs": {
+    "url": "https://github.com/core-spec-tech/vite-plugin-api-auto-login/issues"
+  }
+}