@homeflare/alchemy 0.12.0 → 0.13.0

package/src/proxmox/write-only.test.ts

@@ -0,0 +1,75 @@
+/**
+ * write-only.ts — resolving `{ fromEnv }` and the seal a plan compares instead of a value.
+ *
+ * ★ THE SEAL IS THE WHOLE CHANGE-DETECTION STORY FOR A SECRET THE SERVER WILL NOT RETURN, so each
+ *   property it relies on is pinned: the same values verify, a different value does not, key order
+ *   does not matter, and nothing malformed ever reads as a match.
+ */
+import { describe, expect, test } from 'bun:test';
+import { resolveAll, seal, sealMatches } from './write-only.ts';
+
+describe('resolveAll', () => {
+  test('resolves by variable name and reports every missing or empty one, by name', () => {
+    const env = { HOOK: 's3cret', EMPTY: '' };
+    const got = resolveAll(
+      { a: { fromEnv: 'HOOK' }, b: { fromEnv: 'EMPTY' }, c: { fromEnv: 'UNSET' } },
+      env,
+    );
+    expect(got.values).toEqual({ a: 's3cret' });
+    expect(got.missing).toEqual(['EMPTY', 'UNSET']);
+  });
+
+  test('does not trim: the value sent is the value in the environment', () => {
+    expect(resolveAll({ a: { fromEnv: 'X' } }, { X: ' v\n' }).values).toEqual({ a: ' v\n' });
+  });
+});
+
+describe('seal', () => {
+  const values = { 'secret:token': 'correct horse', password: 'battery staple' };
+
+  test('verifies the values it was made from, and no others', () => {
+    const sealed = seal(values);
+    expect(sealed).toStartWith('scrypt:');
+    expect(sealMatches(sealed, values)).toBe(true);
+    expect(sealMatches(sealed, { ...values, password: 'battery staplf' })).toBe(false);
+    expect(sealMatches(sealed, { 'secret:token': 'correct horse' })).toBe(false);
+  });
+
+  test('never contains a value, raw or base64', () => {
+    const sealed = seal(values);
+    for (const value of Object.values(values)) {
+      expect(sealed).not.toContain(value);
+      expect(sealed).not.toContain(Buffer.from(value).toString('base64'));
+    }
+  });
+
+  test('key order is not a change', () => {
+    const sealed = seal({ a: '1', b: '2' });
+    expect(sealMatches(sealed, { b: '2', a: '1' })).toBe(true);
+  });
+
+  test('a random salt by default: sealing twice gives two seals that both verify', () => {
+    const one = seal(values);
+    const two = seal(values);
+    expect(one).not.toBe(two);
+    expect(sealMatches(two, values)).toBe(true);
+  });
+
+  test('a fixed salt is deterministic — what a header digest needs to not churn state', () => {
+    expect(seal(values, 'fixed')).toBe(seal(values, 'fixed'));
+    expect(seal(values, 'fixed')).not.toBe(seal(values, 'other'));
+  });
+
+  test('nothing to seal is the empty string, and only nothing matches it', () => {
+    expect(seal({})).toBe('');
+    expect(sealMatches('', {})).toBe(true);
+    expect(sealMatches('', values)).toBe(false);
+  });
+
+  test('a malformed seal is never a match', () => {
+    const [, salt, digest] = seal(values).split(':');
+    for (const bad of [`md5:${salt}:${digest}`, `scrypt:${salt}`, `scrypt:${salt}:${digest}:x`]) {
+      expect(sealMatches(bad, values)).toBe(false);
+    }
+  });
+});

package/src/proxmox/write-only.ts

@@ -0,0 +1,106 @@
+/**
+ * Values a declaration may SEND and must never STORE — a webhook secret, a header carrying a
+ * credential, an smtp password — and the one form in which a plan may still remember them.
+ *
+ * ⛔ A SECRET PROP IS A SECRET IN THE STATE STORE, WHATEVER TYPE IT HAS. Alchemy persists props as
+ *   well as attributes — `delete` is handed `olds`, which can only have come from the store — and
+ *   it does not encrypt either: `StateEncoding.ts` TAGS a `Redacted` value and writes the inner
+ *   value beside the tag. So `Redacted` hides a secret from a log line and from nothing else.
+ *   notification-target.ts (PVE) answered that by making no secret declarable at all, and paid
+ *   for it: an authenticated smtp target or a signed webhook could not be created from code.
+ * ★ SO THE PROP HOLDS A NAME, NOT A VALUE. `{ fromEnv: 'PBS_HOOK_TOKEN' }` names the variable the
+ *   DEPLOYING process reads at call time — the shape forgejo/org-actions-secrets.ts already uses.
+ *   The name is what lands in state; the value exists only in that process's memory and on the
+ *   wire to the server.
+ *
+ * ⚠️ A PLAN STILL NEEDS TO KNOW WHETHER A VALUE CHANGED, AND IT CANNOT ASK THE SERVER. PBS returns a
+ *   webhook secret's NAME and never its value, and never returns an smtp password at all. So what
+ *   was last written is remembered as a SEAL: a salted scrypt digest, which lets the next plan
+ *   check "is the value in my environment the one I wrote" without the store holding anything a
+ *   reader could send to PBS.
+ *   ⚠️ A DIGEST OF A GUESSABLE SECRET IS STILL GUESSABLE. The salt defeats precomputed tables and
+ *     scrypt makes each guess cost memory and time; neither makes a dictionary word safe. The
+ *     remedy is a secret worth the name — a random token — not a faster hash.
+ */
+import { Buffer } from 'node:buffer';
+import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+
+/** A write-only value, by the NAME of the environment variable holding it. Never the value. */
+export interface FromEnv {
+  readonly fromEnv: string;
+}
+
+/** Where a value is looked up. Defaults to `process.env`, read at call time, never at load. */
+export type Environment = Readonly<Record<string, string | undefined>>;
+
+/**
+ * Each `name → FromEnv` resolved, or the variable names that could not be.
+ *
+ * ⚠️ AN EMPTY VARIABLE IS A MISSING ONE. A secret renderer that failed writes `NAME=` rather than
+ *   omitting the line, and sending `''` would store an empty secret on the server — a webhook that
+ *   authenticates with nothing, reported as a successful deploy.
+ * ⚠️ THE VALUE IS NOT TRIMMED. A token with a trailing newline is a broken header either way, and
+ *   trimming here would make the seal disagree with a value written by any other tool.
+ */
+export const resolveAll = (
+  refs: Readonly<Record<string, FromEnv>>,
+  env: Environment = process.env,
+): { readonly values: Readonly<Record<string, string>>; readonly missing: readonly string[] } => {
+  const values: Record<string, string> = {};
+  const missing: string[] = [];
+  for (const [key, ref] of Object.entries(refs)) {
+    const value = env[ref.fromEnv];
+    if (value === undefined || value === '') missing.push(ref.fromEnv);
+    else values[key] = value;
+  }
+  return { missing: [...new Set(missing)].sort(), values };
+};
+
+/**
+ * ★ PARAMETERS ARE NODE'S OWN SCRYPT DEFAULTS (N 2^14, r 8, p 1) — 16 MiB and tens of
+ *   milliseconds per digest. Plan runs it a handful of times per resource, which is noise, and a
+ *   guesser runs it once per guess, which is the point.
+ */
+const COST = { N: 16_384, maxmem: 64 * 1024 * 1024, p: 1, r: 8 } as const;
+const PREFIX = 'scrypt';
+
+/** Key order must not change a digest, so entries are sorted and serialised as JSON pairs. */
+const canonical = (values: Readonly<Record<string, string>>): string =>
+  JSON.stringify(
+    Object.keys(values)
+      .sort()
+      .map((key) => [key, values[key]]),
+  );
+
+const digest = (salt: Buffer, values: Readonly<Record<string, string>>): Buffer =>
+  scryptSync(canonical(values), salt, 32, COST);
+
+/**
+ * `scrypt:<salt>:<digest>`, or `''` when there is nothing to seal.
+ *
+ * ★ A RANDOM SALT BY DEFAULT, FOR WHAT THIS PROVIDER WROTE. Pass a fixed one only for a value the
+ *   server returns anyway (a header), where a fresh salt per read would churn the state row on
+ *   every plan without protecting anything the server does not already show its auditors.
+ */
+export const seal = (values: Readonly<Record<string, string>>, salt?: string): string => {
+  if (Object.keys(values).length === 0) return '';
+  const bytes = salt === undefined ? randomBytes(16) : Buffer.from(salt, 'utf8');
+  return `${PREFIX}:${bytes.toString('base64url')}:${digest(bytes, values).toString('base64url')}`;
+};
+
+/**
+ * Whether `values` are the ones `sealed` was made from.
+ *
+ * ⚠️ A MALFORMED OR EMPTY SEAL ANSWERS FALSE, never throws: callers decide what "no evidence"
+ *   means, and every caller here treats it as "cannot tell" rather than as drift.
+ */
+export const sealMatches = (sealed: string, values: Readonly<Record<string, string>>): boolean => {
+  if (sealed === '') return Object.keys(values).length === 0;
+  const [prefix, salt, stored, extra] = sealed.split(':');
+  if (prefix !== PREFIX || salt === undefined || stored === undefined || extra !== undefined) {
+    return false;
+  }
+  const expected = Buffer.from(stored, 'base64url');
+  const actual = digest(Buffer.from(salt, 'base64url'), values);
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+};

package/src/verify/fake-engine.ts

@@ -130,6 +130,11 @@ export interface FakeEngine {
   readonly deploy: (body: Body) => Promise<Record<string, string>>;
   /** Verify `body` against what the earlier deploys recorded. */
   readonly verify: (body: Body, options?: VerifyOptions) => Promise<AdoptReport>;
+  /**
+   * Every state row the store holds, as JSON — what a Postgres store would persist. ★ For tests
+   * that must prove a value NEVER reaches state (proxmox/pbs-notification-target-state.test.ts).
+   */
+  readonly stored: () => string;
 }
 
 /**
@@ -138,7 +143,8 @@ export interface FakeEngine {
  * ⚠️ THE CASTS ARE AT THE ENGINE'S TYPED BOUNDARY — openbao/fake-stack.ts has the reasoning.
  */
 export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): FakeEngine => {
-  const state = Alchemy.inMemoryState();
+  const rows: NonNullable<Parameters<typeof Alchemy.inMemoryState>[0]> = {};
+  const state = Alchemy.inMemoryState(rows);
   const stack = Alchemy.Stack as unknown as (
     name: string,
     options: { providers: typeof layer; state: typeof state },
@@ -161,6 +167,7 @@ export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): Fake
     );
 
   return {
+    stored: () => JSON.stringify(rows),
     deploy: (body) =>
       run(body, (compiled) =>
         Effect.gen(function* () {