@blakearoberts/visage 0.0.1-rc.1 → 0.0.1-rc.4

package/dist/certs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"certs.d.ts","sourceRoot":"","sources":["../src/certs.ts"],"names":[],"mappings":"AAMA,KAAK,OAAO,GAAG;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,WAAW,CAAC,EAChC,GAAG,EACH,KAAK,EACL,QAAQ,GACT,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCzB"}
+{"version":3,"file":"certs.d.ts","sourceRoot":"","sources":["../src/certs.ts"],"names":[],"mappings":"AAOA,KAAK,OAAO,GAAG;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,WAAW,CAAC,EAChC,GAAG,EACH,KAAK,EACL,QAAQ,GACT,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCzB"}

package/dist/config.d.ts

@@ -43,6 +43,9 @@ type ResolvedOAuth2Client = {
     readonly scopes: readonly string[];
     readonly public: boolean;
 };
+type ResolvedUpstream = VisageUpstream & {
+    readonly scheme: NonNullable<VisageUpstream['scheme']>;
+};
 type ResolvedVisageOptions = {
     readonly host: string;
     readonly port: number;
@@ -50,7 +53,7 @@ type ResolvedVisageOptions = {
     readonly idp: ResolvedIdpOption;
     readonly oauth2: ResolvedOAuth2Client;
     readonly services?: Record<string, VisageService>;
-    readonly upstreams?: Record<string, VisageUpstream>;
+    readonly upstreams?: Record<string, ResolvedUpstream>;
 };
 export type VisageConfig = {
     readonly host: string;
@@ -68,9 +71,9 @@ export type VisageConfig = {
         readonly oauth2ProxyClientSecret: Volume;
     };
     readonly services: Readonly<Record<string, VisageService>>;
-    readonly upstreams: Readonly<Record<string, VisageUpstream>>;
+    readonly upstreams: Readonly<Record<string, ResolvedUpstream>>;
 };
-export declare function resolveOptions(options: VisageOptions): ResolvedVisageOptions;
+export declare function resolveOptions({ host, port, cookie, idp, oauth2, services, upstreams, }: VisageOptions): ResolvedVisageOptions;
 export declare function resolveConfig(options: ResolvedVisageOptions, config: ResolvedConfig, vitePort: number): VisageConfig;
 export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,6 +1,7 @@
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, createWriteStream, chmodSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { stringify } from 'yaml';
@@ -63,10 +64,11 @@ async function ensureCerts({ bin, certs, hostname, }) {
     const mkcert = await ensureMkCert(bin);
     const env = {
         ...process.env,
-        CAROOT: join(bin, 'ca'),
+        CAROOT: join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'visage/ca'),
         TRUST_STORES: process.env.TRUST_STORES ?? 'system',
     };
-    // install CA
+    mkdirSync(env.CAROOT, { recursive: true });
+    // mkcert -install is idempotent; CA files alone do not prove trust-store state.
     {
         const result = spawnSync(mkcert, ['-install'], {
             env,
@@ -268,7 +270,11 @@ http {
             <%_ if (location.auth?.enabled && location.auth.forward) { %>
             proxy_set_header Authorization "Bearer $access_token";
             <%_ } %>
-            proxy_pass http://<%~ name %>;
+            <%_ if (upstream.scheme === 'https') { %>
+            proxy_ssl_server_name on;
+            proxy_ssl_name <%~ upstream.host %>;
+            <%_ } %>
+            proxy_pass <%~ upstream.scheme %>://<%~ name %>;
         }
             <%_ } %>
 
@@ -389,11 +395,13 @@ const BaseServices = {
 };
 const BaseDexUpstream = {
     host: 'dex',
+    scheme: 'http',
     port: 5556,
     locations: { '/dex/': { auth: { enabled: false } } },
 };
 const BaseOauth2ProxyUpstream = {
     host: 'oauth2_proxy',
+    scheme: 'http',
     port: 4180,
     locations: {
         '/oauth2/': {
@@ -411,6 +419,7 @@ const BaseOauth2ProxyUpstream = {
 };
 const BaseViteUpstream = {
     host: 'host.docker.internal',
+    scheme: 'http',
     locations: {
         '/': {
             auth: { forward: false, redirect: true },
@@ -440,7 +449,7 @@ const DefaultIdpConfig = {
 const DefaultOAuth2Client = {
     id: 'visage',
     secret: 'visage-secret',
-    scopes: ['openid', 'email', 'profile']};
+    scopes: ['openid', 'email', 'profile', 'offline_access']};
 const DefaultProxyPolicy = {
     auth: { enabled: true, forward: true, redirect: false },
     headers: {
@@ -451,15 +460,12 @@ const DefaultProxyPolicy = {
         'X-Forwarded-Proto': '$scheme',
     },
 };
-function resolveOptions(options) {
-    const cookie = options.cookie ?? {};
+function resolveOptions({ host = 'local.vite.app', port = 9001, cookie = {}, idp, oauth2 = {}, services, upstreams, }) {
     const cookieName = cookie.name ?? 'session';
-    const oauth2 = options.oauth2 ?? {};
     const publicClient = oauth2.clientSecret === null;
     return {
-        ...options,
-        host: options.host ?? 'local.vite.app',
-        port: options.port ?? 9001,
+        host,
+        port,
         cookie: {
             ...DefaultCookiePolicy,
             cookie_name: cookie.domains === undefined
@@ -476,7 +482,7 @@ function resolveOptions(options) {
                 : { cookie_domains: cookie.domains }),
             ...(cookie.path === undefined ? {} : { cookie_path: cookie.path }),
         },
-        idp: resolveIdpOption(options.idp),
+        idp: resolveIdpOption(idp),
         oauth2: {
             id: oauth2.clientId ?? DefaultOAuth2Client.id,
             ...(publicClient
@@ -485,6 +491,15 @@ function resolveOptions(options) {
             scopes: oauth2.scopes ?? DefaultOAuth2Client.scopes,
             public: publicClient,
         },
+        ...(services === undefined ? {} : { services }),
+        ...(upstreams === undefined
+            ? {}
+            : {
+                upstreams: Object.fromEntries(Object.entries(upstreams).map(([name, upstream]) => [
+                    name,
+                    { ...upstream, scheme: upstream.scheme ?? 'http' },
+                ])),
+            }),
     };
 }
 function resolveIdpOption(idp) {
@@ -518,9 +533,9 @@ function resolveConfig(options, config, vitePort) {
         ...(options.idp.kind === 'dex' ? { dex: BaseDexUpstream } : {}),
         ...options.upstreams,
     };
-    const { host: idpHost, port: idpPort } = upstreams[options.idp.upstream];
+    const { host: idpHost, port: idpPort, scheme: idpScheme, } = upstreams[options.idp.upstream];
     const origin = `https://${options.host}:${options.port}`;
-    const idpOrigin = `http://${idpHost}:${idpPort}`;
+    const idpOrigin = `${idpScheme}://${idpHost}:${idpPort}`;
     const idpBase = {
         upstream: options.idp.upstream,
         issuer: options.idp.issuer ?? `${origin}${options.idp.path}`,

package/dist/render/nginx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nginx.d.ts","sourceRoot":"","sources":["../../src/render/nginx.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAmD9C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAI3D"}
+{"version":3,"file":"nginx.d.ts","sourceRoot":"","sources":["../../src/render/nginx.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAuD9C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAI3D"}

package/dist/render/oauth2-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth2-proxy.d.ts","sourceRoot":"","sources":["../../src/render/oauth2-proxy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAQjE"}
+{"version":3,"file":"oauth2-proxy.d.ts","sourceRoot":"","sources":["../../src/render/oauth2-proxy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAWjE"}

package/dist/types.d.ts

@@ -1,22 +1,97 @@
+/**
+ * User-configurable options for the Visage Vite plugin.
+ */
 export type VisageOptions = {
+    /**
+     * Browser-facing hostname for the local Visage HTTPS origin.
+     *
+     * @defaultValue `'local.vite.app'`
+     */
     readonly host?: string;
+    /**
+     * Browser-facing HTTPS port for the local Visage proxy.
+     *
+     * @defaultValue `9001`
+     */
     readonly port?: number;
+    /**
+     * Session cookie settings normalized into OAuth2 Proxy configuration.
+     */
     readonly cookie?: VisageCookiePolicy;
+    /**
+     * Identity provider configuration. Omit this to use Visage's managed Dex
+     * provider.
+     */
     readonly idp?: VisageDexOptions | VisageIdpOptions;
+    /**
+     * OAuth2 client settings shared by Dex or an external IdP and OAuth2 Proxy.
+     */
     readonly oauth2?: VisageOAuth2Client;
+    /**
+     * Additional or replacement Docker Compose services managed with the Vite
+     * dev-server lifecycle.
+     */
     readonly services?: Record<string, VisageService>;
+    /**
+     * Upstream targets that NGINX can route to by path.
+     */
     readonly upstreams?: Record<string, VisageUpstream>;
 };
+/**
+ * Cookie lifetime, scope, and naming policy for the OAuth2 Proxy session.
+ */
 export type VisageCookiePolicy = {
+    /**
+     * Session cookie name. Host-only cookies are automatically prefixed with
+     * `__HOST-` when no domains are configured, so the default rendered
+     * host-only cookie name is `__HOST-session`.
+     *
+     * @defaultValue `'session'`
+     */
     readonly name?: string;
+    /**
+     * Maximum cookie lifetime using an OAuth2 Proxy duration string.
+     *
+     * @defaultValue `'8h'`
+     */
     readonly expire?: string;
+    /**
+     * Interval after which OAuth2 Proxy refreshes the session using an OAuth2
+     * Proxy duration string.
+     *
+     * @defaultValue `'15m'`
+     */
     readonly refresh?: string;
+    /**
+     * Cookie domains for sharing the session across local hostnames. Leave unset
+     * for a host-only cookie.
+     */
     readonly domains?: readonly string[];
+    /**
+     * Cookie path scope.
+     *
+     * @defaultValue `'/'`
+     */
     readonly path?: string;
 };
+/**
+ * Managed Dex identity provider options.
+ */
 export type VisageDexOptions = {
+    /**
+     * Selects the managed Dex provider. Omit this for the default managed Dex
+     * provider.
+     */
     readonly kind?: 'dex';
+    /**
+     * Token expiration and rotation settings rendered into the Dex config.
+     */
     readonly expiry?: VisageDexExpiry;
+    /**
+     * Static username/password users rendered into the Dex config.
+     *
+     * @defaultValue `[{ email: 'user@example.com', password: 'pass' }]`
+     */
     readonly users?: readonly VisageDexUser[];
 };
 /**
@@ -25,59 +100,217 @@ export type VisageDexOptions = {
  * @see {@link https://dexidp.io/docs/configuration/tokens/#expiration-and-rotation-settings}
  */
 export type VisageDexExpiry = {
+    /**
+     * Lifetime for ID tokens issued by Dex.
+     */
     readonly idTokens?: string;
+    /**
+     * Lifetime for in-progress authorization requests.
+     */
     readonly authRequests?: string;
+    /**
+     * Lifetime for in-progress device authorization requests.
+     */
     readonly deviceRequests?: string;
+    /**
+     * Rotation interval for Dex signing keys.
+     */
     readonly signingKeys?: string;
+    /**
+     * Refresh token lifetime and rotation settings.
+     */
     readonly refreshTokens?: {
+        /**
+         * Maximum time a refresh token may go unused before it expires.
+         */
         readonly validIfNotUsedFor?: string;
+        /**
+         * Absolute lifetime for refresh tokens, regardless of use.
+         */
         readonly absoluteLifetime?: string;
+        /**
+         * Whether Dex should skip refresh-token rotation.
+         */
         readonly disableRotation?: boolean;
+        /**
+         * Grace period during which a rotated refresh token may be reused.
+         */
         readonly reuseInterval?: string;
     };
 };
+/**
+ * Static user rendered into the managed Dex password database.
+ */
 export type VisageDexUser = {
+    /**
+     * Email address used as the Dex login identifier.
+     */
     readonly email: string;
+    /**
+     * Plain-text development password. Visage hashes this before rendering the
+     * Dex config.
+     */
     readonly password: string;
+    /**
+     * Display username. Defaults to the portion of {@link VisageDexUser.email}
+     * before `@`.
+     */
     readonly username?: string;
+    /**
+     * Stable Dex user ID. Defaults to {@link VisageDexUser.email}.
+     */
     readonly userID?: string;
 };
+/**
+ * External OpenID Connect identity provider options.
+ */
 export type VisageIdpOptions = {
+    /**
+     * Selects the external IdP flow.
+     */
     readonly kind: 'external';
+    /**
+     * Name of the configured upstream that serves the external IdP.
+     */
     readonly upstream: string;
+    /**
+     * Public path where the external IdP is exposed through Visage.
+     *
+     * @defaultValue `'/dex'`
+     */
     readonly path?: string;
+    /**
+     * OIDC issuer URL. Defaults to the Visage origin plus
+     * {@link VisageIdpOptions.path}.
+     */
     readonly issuer?: string;
+    /**
+     * Browser-facing authorization endpoint URL. Defaults to the Visage origin
+     * plus {@link VisageIdpOptions.path} and `/auth`.
+     */
     readonly authorizationEndpoint?: string;
+    /**
+     * Token endpoint URL used by OAuth2 Proxy.
+     *
+     * Defaults to the configured IdP upstream origin plus
+     * {@link VisageIdpOptions.path} and `/token`.
+     */
     readonly tokenEndpoint?: string;
+    /**
+     * JWKS endpoint URL used by OAuth2 Proxy.
+     *
+     * Defaults to the configured IdP upstream origin plus
+     * {@link VisageIdpOptions.path} and `/keys`.
+     */
     readonly jwksEndpoint?: string;
 };
+/**
+ * OAuth2 client configuration used by OAuth2 Proxy and, for managed Dex, the
+ * rendered Dex static client.
+ */
 export type VisageOAuth2Client = {
+    /**
+     * OAuth2 client identifier.
+     *
+     * @defaultValue `'visage'`
+     */
     readonly clientId?: string;
     /**
-     * Set to `null` to render a public Dex client and enable OAuth2 Proxy PKCE.
+     * OAuth2 client secret.
+     *
+     * Set to `null` for a public OAuth2 client. OAuth2 Proxy uses PKCE, and
+     * managed Dex renders a public static client.
+     *
+     * @defaultValue `'visage-secret'`
      */
     readonly clientSecret?: string | null;
+    /**
+     * OIDC scopes requested by OAuth2 Proxy.
+     *
+     * @defaultValue `['openid', 'email', 'profile', 'offline_access']`
+     */
     readonly scopes?: readonly string[];
 };
+/**
+ * Subset of a Docker Compose service definition managed by Visage.
+ */
 export type VisageService = {
+    /**
+     * Container image reference used for the service.
+     */
     readonly image: string;
+    /**
+     * Optional command override rendered into the Compose service.
+     */
     readonly command?: readonly string[];
+    /**
+     * Compose service dependencies that should start before this service.
+     */
     readonly depends_on?: readonly string[];
+    /**
+     * Additional host-to-IP mappings rendered into the Compose service.
+     */
     readonly extra_hosts?: readonly string[];
 };
+/**
+ * Named proxy target that NGINX routes to for one or more locations.
+ */
 export type VisageUpstream = {
+    /**
+     * Hostname or Compose service name NGINX should proxy to.
+     */
     readonly host: string;
+    /**
+     * URL scheme NGINX should use when proxying to this upstream.
+     *
+     * @defaultValue `'http'`
+     */
+    readonly scheme?: 'http' | 'https';
+    /**
+     * Port NGINX should proxy to on {@link VisageUpstream.host}.
+     */
     readonly port: number;
+    /**
+     * Path-location policies for this upstream, keyed by NGINX location path.
+     */
     readonly locations?: {
         readonly [path: string]: VisageProxyPolicy;
     };
 };
+/**
+ * Per-location NGINX authentication and header forwarding policy.
+ */
 export type VisageProxyPolicy = {
+    /**
+     * OAuth2 authentication behavior for this location.
+     */
     readonly auth?: {
+        /**
+         * Whether requests to this location require OAuth2 authentication.
+         *
+         * @defaultValue `true`
+         */
         readonly enabled?: boolean;
+        /**
+         * Whether unauthenticated browser requests should redirect to sign-in.
+         *
+         * @defaultValue `false`
+         */
         readonly redirect?: boolean;
+        /**
+         * Whether the authenticated access token should be forwarded upstream as an
+         * `Authorization: Bearer ...` header.
+         *
+         * @defaultValue `true`
+         */
         readonly forward?: boolean;
     };
+    /**
+     * Request headers to set when proxying to the upstream. Values may include
+     * NGINX variables. These are merged with Visage's default proxy headers:
+     * `Cookie`, `Host`, `X-Real-IP`, `X-Forwarded-For`, and
+     * `X-Forwarded-Proto`.
+     */
     readonly headers?: {
         readonly [key: string]: string;
     };

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blakearoberts/visage",
-  "version": "0.0.1-rc.1",
+  "version": "0.0.1-rc.4",
   "description": "Vite plugin for local development with HMR and OIDC session cookie lifecycle semantics.",
   "type": "module",
   "author": "Blake Roberts",
@@ -46,12 +46,15 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "test": "npm run test:unit",
     "test:e2e": "playwright test test/e2e",
-    "test:unit": "node --experimental-strip-types --test test/unit/*.test.ts"
+    "test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
+    "format": "prettier --write \"{docs,examples,src,test}/**/*.{ts,tsx,js,jsx,json,css,html,md}\" \"*.{json,md}\"",
+    "format:check": "prettier --check \"{docs,examples,src,test}/**/*.{ts,tsx,js,jsx,json,css,html,md}\" \"*.{json,md}\""
   },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/node": "^25.6.2",
+    "prettier": "^3.8.3",
     "rollup": "^4.60.3",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",