@joinremba/beacon 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/beacon",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Validate environment variables, config, secrets, and runtime feature gates before production breaks.",
   "type": "module",
   "main": "./src/index.ts",
@@ -68,6 +68,7 @@
     "bun": ">=1.3.1"
   },
   "dependencies": {
+    "@joinremba/core": "^0.4.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {

package/src/cli-config.ts

@@ -1,5 +1,5 @@
-import { z } from "zod";
 import type { FeatureGate, SchemaEntry } from "./types";
+import { typeToSchema, type SchemaField } from "./schema";
 
 export interface BeaconConfigFile {
   schema: Record<string, SchemaEntry>;
@@ -119,49 +119,7 @@ export function generateEnvExample(config: BeaconConfigFile, activeProfile?: str
   return lines.join("\n");
 }
 
-const typeToSchema = (entry: Record<string, unknown>): z.ZodType<unknown> => {
-  const type = entry.type as string;
-  let base: z.ZodType<unknown>;
-
-  switch (type) {
-    case "string":
-    case "host":
-      base = z.string();
-      break;
-    case "url":
-      base = z.string().url();
-      break;
-    case "number":
-      base = z.coerce.number();
-      break;
-    case "integer":
-      base = z.coerce.number().int();
-      break;
-    case "boolean":
-      base = z
-        .string()
-        .transform((v) => v === "true" || v === "1")
-        .pipe(z.boolean());
-      break;
-    case "enum":
-      base = z.enum((entry.values ?? []) as unknown as [string, ...string[]]);
-      break;
-    case "port":
-      base = z.coerce.number().int().min(1).max(65535);
-      break;
-    case "email":
-      base = z.string().email();
-      break;
-    default:
-      base = z.string();
-  }
-
-  if (entry.default !== undefined) {
-    base = base.default(entry.default as string | number | boolean);
-  }
-
-  return base;
-};
+const SECRET_CENSOR = "[REDACTED]";
 
 export async function runCheck(
   config: BeaconConfigFile,
@@ -206,19 +164,22 @@ export async function runCheck(
       continue;
     }
 
+    const isSecret = isField ? (entry as { secret?: boolean }).secret : false;
+    const display = isSecret ? SECRET_CENSOR : raw;
+
     try {
       if (isField) {
-        const schema = typeToSchema(entry as unknown as Record<string, unknown>);
+        const schema = typeToSchema(entry as SchemaField);
         schema.parse(raw);
       }
       results.push({
         key,
         status: "ok",
-        message: `Set (${raw.length > 25 ? raw.substring(0, 25) + "..." : raw})`,
+        message: `Set (${display.length > 25 ? display.substring(0, 25) + "..." : display})`,
       });
     } catch {
-      results.push({ key, status: "invalid", message: `Invalid: "${raw}"` });
-      errors.push({ key, message: `Invalid value: ${raw}` });
+      results.push({ key, status: "invalid", message: `Invalid: "${display}"` });
+      errors.push({ key, message: `Invalid value: ${display}` });
     }
   }
 

package/src/cli.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, describe } from "bun:test";
-import { generateEnvExample } from "./cli-config";
+import { generateEnvExample, runCheck } from "./cli-config";
 import type { BeaconConfigFile } from "./cli-config";
 
 describe("generateEnvExample", () => {
@@ -51,3 +51,53 @@ describe("generateEnvExample", () => {
     expect(result).toContain("Secret: yes");
   });
 });
+
+describe("runCheck", () => {
+  test("returns ok for present and valid env vars", async () => {
+    const prev = process.env.TEST_DB_URL;
+    process.env.TEST_DB_URL = "https://example.com/db";
+    try {
+      const config: BeaconConfigFile = {
+        schema: {
+          TEST_DB_URL: { type: "url", required: true },
+        },
+      };
+      const result = await runCheck(config);
+      expect(result.results).toHaveLength(1);
+      expect(result.results[0]?.status).toBe("ok");
+    } finally {
+      if (prev === undefined) delete process.env.TEST_DB_URL;
+      else process.env.TEST_DB_URL = prev;
+    }
+  });
+
+  test("returns missing for absent required var", async () => {
+    delete process.env.TEST_MISSING;
+    const config: BeaconConfigFile = {
+      schema: {
+        TEST_MISSING: { type: "string", required: true },
+      },
+    };
+    const result = await runCheck(config);
+    expect(result.results[0]?.status).toBe("missing");
+  });
+
+  test("redacts secret values on invalid", async () => {
+    const prev = process.env.TEST_SECRET;
+    process.env.TEST_SECRET = "my-secret-value-that-should-not-leak";
+    try {
+      const config: BeaconConfigFile = {
+        schema: {
+          TEST_SECRET: { type: "integer", secret: true },
+        },
+      };
+      const result = await runCheck(config);
+      expect(result.results[0]?.status).toBe("invalid");
+      expect(result.results[0]?.message).not.toContain("my-secret-value");
+      expect(result.errors[0]?.message).not.toContain("my-secret-value");
+    } finally {
+      if (prev === undefined) delete process.env.TEST_SECRET;
+      else process.env.TEST_SECRET = prev;
+    }
+  });
+});

package/src/encryption.ts

@@ -2,26 +2,26 @@ const ALGORITHM = "AES-GCM";
 const IV_LENGTH = 12;
 const TAG_LENGTH = 128;
 
-function keyToBuf(key: Uint8Array): ArrayBuffer {
-  const buf = new ArrayBuffer(key.byteLength);
-  new Uint8Array(buf).set(key);
-  return buf;
-}
-
 async function deriveKey(password: string): Promise<CryptoKey> {
-  const encoded = new TextEncoder().encode(password);
-  const raw =
-    encoded.length >= 32
-      ? encoded.slice(0, 32)
-      : (() => {
-          const p = new Uint8Array(32);
-          p.set(encoded);
-          return p;
-        })();
-  return crypto.subtle.importKey("raw", keyToBuf(raw), { name: ALGORITHM }, false, [
-    "encrypt",
-    "decrypt",
-  ]);
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(password),
+    "HKDF",
+    false,
+    ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new Uint8Array(32),
+      info: new TextEncoder().encode("beacon-env-encryption-v1"),
+    },
+    keyMaterial,
+    { name: ALGORITHM, length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
 }
 
 export async function encryptEnv(envContent: string, key: string): Promise<string> {

package/src/index.test.ts

@@ -1,4 +1,4 @@
-import { expect, test, beforeAll } from "bun:test";
+import { expect, test, beforeEach, mock } from "bun:test";
 import { createBeacon, ConfigValidationError } from "./index";
 import { z } from "zod";
 
@@ -6,11 +6,11 @@ const zodStringMin3 = z.string().min(3);
 
 const ORIGINAL_ENV = { ...process.env };
 
-beforeAll(() => {
+beforeEach(() => {
   process.env = { ...ORIGINAL_ENV };
 });
 
-test("returns typed config values after ensure()", () => {
+test("returns typed config values after ensure()", async () => {
   process.env.DATABASE_URL = "https://example.com/db";
   process.env.REDIS_URL = "https://example.com/redis";
 
@@ -19,44 +19,44 @@ test("returns typed config values after ensure()", () => {
     REDIS_URL: { type: "url", required: true },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<string>("DATABASE_URL")).toBe("https://example.com/db");
   expect(config.get<string>("REDIS_URL")).toBe("https://example.com/redis");
 });
 
-test("throws ValidationError for missing required vars", () => {
+test("throws ValidationError for missing required vars", async () => {
   delete process.env.MISSING_VAR;
 
   const config = createBeacon({
     MISSING_VAR: { type: "string", required: true },
   });
 
-  expect(() => config.ensure()).toThrow(ConfigValidationError);
+  await expect(config.ensure()).rejects.toThrow(ConfigValidationError);
 });
 
-test("does not throw for optional vars with defaults", () => {
+test("does not throw for optional vars with defaults", async () => {
   delete process.env.MY_PORT;
 
   const config = createBeacon({
     MY_PORT: { type: "port", default: 3000 },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<number>("MY_PORT")).toBe(3000);
 });
 
-test("coerces number types", () => {
+test("coerces number types", async () => {
   process.env.MY_NUMBER = "42";
 
   const config = createBeacon({
     MY_NUMBER: { type: "number" },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<number>("MY_NUMBER")).toBe(42);
 });
 
-test("coerces boolean types", () => {
+test("coerces boolean types", async () => {
   process.env.FEATURE_X = "true";
   process.env.FEATURE_Y = "false";
   process.env.FEATURE_Z = "1";
@@ -67,13 +67,13 @@ test("coerces boolean types", () => {
     FEATURE_Z: { type: "boolean" },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<boolean>("FEATURE_X")).toBe(true);
   expect(config.get<boolean>("FEATURE_Y")).toBe(false);
   expect(config.get<boolean>("FEATURE_Z")).toBe(true);
 });
 
-test("validates enum values", () => {
+test("validates enum values", async () => {
   process.env.NODE_ENV = "production";
 
   const config = createBeacon({
@@ -83,11 +83,11 @@ test("validates enum values", () => {
     },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<string>("NODE_ENV")).toBe("production");
 });
 
-test("throws for invalid enum values", () => {
+test("throws for invalid enum values", async () => {
   process.env.NODE_ENV = "invalid";
 
   const config = createBeacon({
@@ -97,17 +97,17 @@ test("throws for invalid enum values", () => {
     },
   });
 
-  expect(() => config.ensure()).toThrow();
+  await expect(config.ensure()).rejects.toThrow();
 });
 
-test("validates port range", () => {
+test("validates port range", async () => {
   process.env.PORT = "99999";
 
   const config = createBeacon({
     PORT: { type: "port" },
   });
 
-  expect(() => config.ensure()).toThrow();
+  await expect(config.ensure()).rejects.toThrow();
 });
 
 test("throws when accessing before ensure()", () => {
@@ -118,7 +118,7 @@ test("throws when accessing before ensure()", () => {
   expect(() => config.get("DB_URL")).toThrow("Call beacon.ensure()");
 });
 
-test("uses profile overrides when profile is set", () => {
+test("uses profile overrides when profile is set", async () => {
   process.env.DB_HOST = "prod.example.com";
 
   const config = createBeacon(
@@ -135,22 +135,22 @@ test("uses profile overrides when profile is set", () => {
     }
   );
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<string>("DB_HOST")).toBe("prod.example.com");
 });
 
-test("accepts Zod schemas directly", () => {
+test("accepts Zod schemas directly", async () => {
   process.env.ZOD_VAR = "hello";
 
   const config = createBeacon({
     ZOD_VAR: { schema: zodStringMin3 },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<string>("ZOD_VAR")).toBe("hello");
 });
 
-test("collects all errors before throwing", () => {
+test("collects all errors before throwing", async () => {
   delete process.env.VAR_A;
   delete process.env.VAR_B;
 
@@ -159,13 +159,18 @@ test("collects all errors before throwing", () => {
     VAR_B: { type: "number", required: true },
   });
 
-  try {
-    config.ensure();
-    expect.unreachable();
-  } catch (err) {
-    expect(err).toBeInstanceOf(ConfigValidationError);
-    expect((err as ConfigValidationError).errors).toHaveLength(2);
-  }
+  await expect(config.ensure()).rejects.toBeInstanceOf(ConfigValidationError);
+});
+
+test("ensure({ strict: false }) skips missing required vars without throwing", async () => {
+  delete process.env.STRICT_VAR;
+
+  const config = createBeacon({
+    STRICT_VAR: { type: "string", required: true },
+    OPTIONAL_VAR: { type: "number", required: false },
+  });
+
+  await expect(config.ensure({ strict: false })).resolves.toBeDefined();
 });
 
 test("tracks secret keys", () => {
@@ -262,3 +267,72 @@ test("isEnabled returns false when feature is killed", () => {
   );
   expect(config.isEnabled("newDashboard")).toBe(false);
 });
+
+test("fetches remote config when client is provided", async () => {
+  const config = createBeacon(
+    { LOCAL_VAR: { type: "string", default: "local" } },
+    {
+      client: {
+        getConfig: mock(async () => [
+          { key: "REMOTE_VAR", value: "from-cloud", secret: false, updatedAt: "" },
+        ]),
+      } as any,
+    }
+  );
+
+  await config.ensure();
+  expect(config.get<string>("REMOTE_VAR")).toBe("from-cloud");
+  expect(config.get<string>("LOCAL_VAR")).toBe("local");
+});
+
+test("schema entries take priority over remote config", async () => {
+  const config = createBeacon(
+    { SHARED_KEY: { type: "string", default: "from-schema" } },
+    {
+      client: {
+        getConfig: mock(async () => [
+          { key: "SHARED_KEY", value: "from-cloud", secret: false, updatedAt: "" },
+        ]),
+      } as any,
+    }
+  );
+
+  await config.ensure();
+  expect(config.get<string>("SHARED_KEY")).toBe("from-schema");
+});
+
+test("remote config fills gaps not in schema", async () => {
+  const config = createBeacon(
+    { DEFINED_KEY: { type: "string", default: "schema-val" } },
+    {
+      client: {
+        getConfig: mock(async () => [
+          { key: "DEFINED_KEY", value: "remote-val", secret: false, updatedAt: "" },
+          { key: "REMOTE_ONLY", value: "remote-only", secret: false, updatedAt: "" },
+        ]),
+      } as any,
+    }
+  );
+
+  await config.ensure();
+  expect(config.get<string>("DEFINED_KEY")).toBe("schema-val");
+  expect(config.get<string>("REMOTE_ONLY")).toBe("remote-only");
+});
+
+test("network error on remote config silently falls back to local", async () => {
+  const { NetworkError } = await import("@joinremba/core");
+
+  const config = createBeacon(
+    { LOCAL_VAR: { type: "string", default: "fallback" } },
+    {
+      client: {
+        getConfig: mock(async () => {
+          throw new NetworkError("connection lost");
+        }),
+      } as any,
+    }
+  );
+
+  await config.ensure();
+  expect(config.get<string>("LOCAL_VAR")).toBe("fallback");
+});

package/src/index.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type {
   Beacon as BeaconInterface,
   BeaconOptions,
+  EnsureOptions,
   FeatureGate,
   FieldDefinition,
   FieldDefinitionWithSchema,
@@ -9,6 +10,7 @@ import type {
   FieldType,
 } from "./types";
 import { ConfigError, ConfigValidationError } from "./errors";
+import { typeToSchema } from "./schema";
 
 export type {
   BeaconOptions,
@@ -21,55 +23,6 @@ export type {
 export { ConfigError, ConfigValidationError };
 export type { BeaconInterface as Beacon };
 
-const typeToSchema = (entry: FieldDefinition): { schema: z.ZodType<unknown>; secret: boolean } => {
-  const secret = entry.secret ?? false;
-  const { type } = entry;
-
-  let base: z.ZodType<unknown>;
-
-  switch (type) {
-    case "string":
-    case "host":
-      base = z.string();
-      break;
-    case "url":
-      base = z.string().url();
-      break;
-    case "number":
-      base = z.coerce.number();
-      break;
-    case "integer":
-      base = z.coerce.number().int();
-      break;
-    case "boolean":
-      base = z
-        .string()
-        .transform((v) => v === "true" || v === "1")
-        .pipe(z.boolean());
-      break;
-    case "enum":
-      if (!entry.values || entry.values.length === 0) {
-        throw new Error(`Enum field must have values defined`);
-      }
-      base = z.enum(entry.values as [string, ...string[]]);
-      break;
-    case "port":
-      base = z.coerce.number().int().min(1).max(65535);
-      break;
-    case "email":
-      base = z.string().email();
-      break;
-    default:
-      base = z.string();
-  }
-
-  if (entry.default !== undefined) {
-    base = base.default(entry.default);
-  }
-
-  return { schema: base, secret };
-};
-
 const resolveEntry = (
   entry: SchemaEntry
 ): {
@@ -80,20 +33,21 @@ const resolveEntry = (
   description?: string;
 } => {
   if ("schema" in entry && entry.schema instanceof z.ZodType) {
+    const hasDefault = entry.schema.safeParse(undefined).success;
     return {
       schema: entry.schema,
       required: entry.required ?? true,
       secret: entry.secret ?? false,
-      hasDefault: false,
+      hasDefault,
       description: entry.description,
     };
   }
   const field = entry as FieldDefinition;
-  const { schema, secret } = typeToSchema(field);
+  const schema = typeToSchema(field);
   return {
     schema,
     required: field.required ?? true,
-    secret,
+    secret: field.secret ?? false,
     hasDefault: field.default !== undefined,
     description: field.description,
   };
@@ -121,6 +75,7 @@ export function createBeacon(
   schema: Record<string, SchemaEntry>,
   options?: BeaconOptions
 ): BeaconInterface {
+  const client = options?.client;
   const mergedSchema: Record<string, SchemaEntry> = { ...schema };
 
   if (options?.profile && options?.profiles?.[options.profile]) {
@@ -139,33 +94,47 @@ export function createBeacon(
   const killSwitches: Record<string, boolean> = options?.killSwitches ?? {};
 
   const beacon: BeaconInterface = {
-    ensure(): BeaconInterface {
+    async ensure(options?: EnsureOptions): Promise<BeaconInterface> {
+      const strict = options?.strict ?? true;
       const errors: ConfigError[] = [];
 
+      if (client) {
+        try {
+          const remote = await client.getConfig();
+          for (const entry of remote) {
+            if (process.env[entry.key] !== undefined) continue;
+            if (mergedSchema[entry.key]) continue;
+            (validated ??= {})[entry.key] = entry.value;
+          }
+        } catch {
+          // Network error — fall back to local-only
+        }
+      }
+
       for (const { key, schema, required, secret, hasDefault } of resolved) {
         const raw = process.env[key];
         const isMissing = raw === undefined || raw === "";
 
-        if (isMissing && hasDefault) {
-          try {
-            const parsed = schema.parse(undefined);
-            (validated ??= {})[key] = parsed;
-          } catch (err) {
-            if (err instanceof z.ZodError) {
-              errors.push(
-                new ConfigError(
-                  key,
-                  `Environment variable ${key}: ${err.issues[0]?.message ?? "Invalid value"}`,
-                  secret
-                )
-              );
+        if (isMissing) {
+          if (hasDefault) {
+            try {
+              const parsed = schema.parse(undefined);
+              (validated ??= {})[key] = parsed;
+            } catch (err) {
+              if (err instanceof z.ZodError) {
+                errors.push(
+                  new ConfigError(
+                    key,
+                    `Environment variable ${key}: ${err.issues[0]?.message ?? "Invalid value"}`,
+                    secret
+                  )
+                );
+              }
             }
+            continue;
           }
-          continue;
-        }
-
-        if (isMissing) {
           if (!required) continue;
+          if (!strict) continue;
           errors.push(
             new ConfigError(key, `Missing required environment variable: ${key}`, secret)
           );
@@ -179,6 +148,7 @@ export function createBeacon(
           if (err instanceof z.ZodError) {
             const issue = err.issues[0];
             const val = secret ? SECRET_CENSOR : raw;
+            if (!strict) continue;
             errors.push(
               new ConfigError(
                 key,

package/src/schema.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+export interface SchemaField {
+  type?: string;
+  default?: unknown;
+  values?: readonly string[];
+}
+
+export function typeToSchema(field: SchemaField): z.ZodType<unknown> {
+  const type = field.type ?? "string";
+  let base: z.ZodType<unknown>;
+
+  switch (type) {
+    case "string":
+    case "host":
+      base = z.string();
+      break;
+    case "url":
+      base = z.string().url();
+      break;
+    case "number":
+      base = z.coerce.number();
+      break;
+    case "integer":
+      base = z.coerce.number().int();
+      break;
+    case "boolean":
+      base = z
+        .string()
+        .transform((v) => v === "true" || v === "1" || v === "yes")
+        .pipe(z.boolean());
+      break;
+    case "enum": {
+      const values = field.values;
+      if (!values || values.length === 0) {
+        throw new Error("Enum field must have values defined");
+      }
+      base = z.enum(values as [string, ...string[]]);
+      break;
+    }
+    case "port":
+      base = z.coerce.number().int().min(1).max(65535);
+      break;
+    case "email":
+      base = z.string().email();
+      break;
+    default:
+      base = z.string();
+  }
+
+  if (field.default !== undefined) {
+    base = base.default(field.default as string | number | boolean);
+  }
+
+  return base;
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import type { Client } from "@joinremba/core";
 
 export type FieldType =
   | "string"
@@ -40,10 +41,17 @@ export interface BeaconOptions {
   profiles?: Record<string, Record<string, SchemaEntry>>;
   features?: Record<string, FeatureGate>;
   killSwitches?: Record<string, boolean>;
+  client?: Client;
+}
+
+export interface EnsureOptions {
+  /** When true (default), throws ConfigValidationError for missing required vars.
+   *  When false, silently skips missing required vars — useful in test environments. */
+  strict?: boolean;
 }
 
 export interface Beacon {
-  ensure(): Beacon;
+  ensure(options?: EnsureOptions): Promise<Beacon>;
   get<T = unknown>(key: string): T;
   readonly secret: Record<string, boolean>;
   isEnabled(feature: string): boolean;