@astralarium/repo-env 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astralarium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,4 @@
-# Temporary Holding Version
+# `@astralarium/repo-env`
 
-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.
+Validated Wrangler bindings shared by workers.
+Apps spread `coreEnvironment(config)` into their environment.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/** OAuth client credentials. */
+export interface OAuthCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+/** Configuration every worker shares; apps extend it with their own fields. */
+export interface CoreConfig {
+    /** Public HTTP(S) origin. */
+    siteOrigin: string;
+    /** Auth signing secret; at least 32 characters. */
+    authSecret: string;
+    /** Postgres connection URL naming a database. */
+    databaseUrl: string;
+    /** Local HTTPS origins auth and the dev server answer beside `siteOrigin`. */
+    localOrigins?: readonly string[];
+}
+/** Wrangler bindings and Hyperdrive override common to an app's workers;
+ *  workers declaring `LOCAL_ORIGINS` answer those origins too. */
+export interface CoreEnvironment extends Record<string, string> {
+    SITE_ORIGIN: string;
+    BETTER_AUTH_SECRET: string;
+    CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_DB_APP: string;
+    LOCAL_ORIGINS: string;
+}
+/** Public bindings available during prerender and at runtime. */
+export interface PublicWebEnvironment {
+    SITE_ORIGIN?: string;
+    LOCAL_ORIGINS?: string;
+}
+/** Absolute HTTP(S) origin, without credentials, path, query or fragment. */
+export declare function parseOrigin(value: string | undefined, key?: string): string;
+/** Deduplicated HTTPS origins from a comma list, with their hosts and hostnames. */
+export declare function parseLocalOrigins(value: string | undefined): {
+    origins: string[];
+    hosts: string[];
+    hostnames: string[];
+};
+/** Optional OAuth pair read from `env[idKey]`/`env[secretKey]`;
+ *  undefined when both are unset, invalid when one is set. */
+export declare function credentialPair<K extends string>(env: Partial<Record<K, string>>, idKey: K, secretKey: K): OAuthCredentials | undefined;
+/** Public configuration; never reads runtime secrets. */
+export declare function publicWebConfig(env: PublicWebEnvironment): {
+    siteOrigin: string;
+    localOrigins: {
+        origins: string[];
+        hosts: string[];
+        hostnames: string[];
+    };
+};
+/** Validated process environment every worker shares. */
+export declare function coreEnvironment(config: CoreConfig): CoreEnvironment;

package/dist/index.js

@@ -0,0 +1,73 @@
+import { ExpectedError } from "@astralarium/repo-telemetry";
+/** Absolute HTTP(S) origin, without credentials, path, query or fragment. */
+export function parseOrigin(value, key = "SITE_ORIGIN") {
+    try {
+        const url = new URL(value ?? "");
+        if (!["http:", "https:"].includes(url.protocol) ||
+            url.username ||
+            url.password ||
+            url.pathname !== "/" ||
+            url.search ||
+            url.hash)
+            throw new Error();
+        return url.origin;
+    }
+    catch {
+        throw new ExpectedError(`${key} must be an HTTP(S) origin`);
+    }
+}
+/** Deduplicated HTTPS origins from a comma list, with their hosts and hostnames. */
+export function parseLocalOrigins(value) {
+    const origins = [
+        ...new Set((value ? value.split(",") : []).map((origin) => {
+            const parsed = parseOrigin(origin.trim(), "LOCAL_ORIGINS");
+            if (!parsed.startsWith("https://"))
+                throw new ExpectedError("LOCAL_ORIGINS must use HTTPS");
+            return parsed;
+        })),
+    ];
+    return {
+        origins,
+        hosts: origins.map((origin) => new URL(origin).host),
+        hostnames: origins.map((origin) => new URL(origin).hostname),
+    };
+}
+/** Optional OAuth pair read from `env[idKey]`/`env[secretKey]`;
+ *  undefined when both are unset, invalid when one is set. */
+export function credentialPair(env, idKey, secretKey) {
+    const clientId = env[idKey];
+    const clientSecret = env[secretKey];
+    if (!clientId && !clientSecret)
+        return undefined;
+    if (!clientId || !clientSecret)
+        throw new ExpectedError(`${idKey} and ${secretKey} must be set together`);
+    return { clientId, clientSecret };
+}
+/** Public configuration; never reads runtime secrets. */
+export function publicWebConfig(env) {
+    return {
+        siteOrigin: parseOrigin(env.SITE_ORIGIN),
+        localOrigins: parseLocalOrigins(env.LOCAL_ORIGINS),
+    };
+}
+/** Validated process environment every worker shares. */
+export function coreEnvironment(config) {
+    if (config.authSecret.length < 32)
+        throw new ExpectedError("BETTER_AUTH_SECRET must contain at least 32 characters");
+    try {
+        const database = new URL(config.databaseUrl);
+        if (!["postgres:", "postgresql:"].includes(database.protocol) ||
+            !database.hostname ||
+            database.pathname.length <= 1)
+            throw new Error();
+    }
+    catch {
+        throw new ExpectedError("DB_APP must be a Postgres connection URL with a database");
+    }
+    return {
+        SITE_ORIGIN: parseOrigin(config.siteOrigin),
+        BETTER_AUTH_SECRET: config.authSecret,
+        CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_DB_APP: config.databaseUrl,
+        LOCAL_ORIGINS: parseLocalOrigins(config.localOrigins?.join(",")).origins.join(","),
+    };
+}

package/dist/testkit/index.d.ts

@@ -0,0 +1,2 @@
+/** Local HTTPS origins a test dev server answers beside its site origin. */
+export declare const TEST_LOCAL_ORIGINS: string[];

package/dist/testkit/index.js

@@ -0,0 +1,5 @@
+/** Local HTTPS origins a test dev server answers beside its site origin. */
+export const TEST_LOCAL_ORIGINS = [
+    "https://localhost:3000",
+    "https://mymac.local:3000",
+];

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@astralarium/repo-env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "homepage": "https://github.com/astralarium/repo/tree/main/packages/repo-env#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astralarium/repo.git",
+    "directory": "packages/repo-env"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./testkit": "./dist/testkit/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@astralarium/repo-telemetry": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "eslint": "^10.2.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3",
+    "@astralarium/repo-config-typescript": "^0.1.0",
+    "@astralarium/repo-config-eslint": "^0.1.0",
+    "@astralarium/repo-package-files": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=24.2"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit",
+    "lint": "eslint",
+    "test": "vitest"
+  }
 }