@ultimat3/core 1.2.0 → 3.0.0

package/src/sampler.ts

@@ -0,0 +1,126 @@
+// Single responsibility: the sampling decision — the one lever between "tracing is on" and "the
+// collector melts". Separate from `telemetry.ts` because the decision is a policy an app replaces,
+// while span construction is not.
+
+import { logger } from './logger';
+import type { SpanAttributes, SpanContext } from './telemetry';
+
+/**
+ * The seam. `parent` is the inbound span context when there is one — an upstream that decided
+ * "not sampled" has said so in `parent.traceFlags`, and a sampler that ignores it splits one
+ * distributed trace into a sampled half and an unsampled half, which is worse than either.
+ */
+export interface Sampler {
+  shouldSample(name: string, parent: SpanContext | undefined, attributes: SpanAttributes): boolean;
+}
+
+export const OTEL_SAMPLER_KEY = 'OTEL_TRACES_SAMPLER';
+export const OTEL_SAMPLER_ARG_KEY = 'OTEL_TRACES_SAMPLER_ARG';
+
+/** Unset means on, exactly as OTel's own `parentbased_always_on` default does. */
+export const DEFAULT_SAMPLE_RATIO = 1;
+
+export const alwaysOnSampler: Sampler = Object.freeze({
+  shouldSample: (): boolean => true,
+});
+
+export const alwaysOffSampler: Sampler = Object.freeze({
+  shouldSample: (): boolean => false,
+});
+
+function parentSampled(parent: SpanContext | undefined): boolean | undefined {
+  return parent === undefined ? undefined : (parent.traceFlags & 1) === 1;
+}
+
+/**
+ * Honour the parent, else sample a `ratio` fraction of new traces.
+ *
+ * `random()` rather than a hash of the trace id: this sampler only ever decides for a ROOT span —
+ * a span with a parent takes the parent's bit verbatim — so there is no second service whose
+ * independent decision has to agree with ours, which is the only thing trace-id hashing buys.
+ * `random` is injectable so the ratio is a test and not a coin flip.
+ */
+export function parentBasedRatioSampler(
+  ratio: number,
+  random: () => number = Math.random,
+): Sampler {
+  return {
+    shouldSample(_name, parent): boolean {
+      const inherited = parentSampled(parent);
+      if (inherited !== undefined) return inherited;
+      if (ratio >= 1) return true;
+      if (ratio <= 0) return false;
+      return random() < ratio;
+    },
+  };
+}
+
+/** `always_off` / `always_on` without the parent-based prefix ignore the inbound decision. */
+export function ratioSampler(ratio: number, random: () => number = Math.random): Sampler {
+  return {
+    shouldSample(): boolean {
+      if (ratio >= 1) return true;
+      if (ratio <= 0) return false;
+      return random() < ratio;
+    },
+  };
+}
+
+function readRatio(raw: string | undefined, spelling: string): number {
+  if (raw === undefined || raw.trim() === '') return DEFAULT_SAMPLE_RATIO;
+  const parsed = Number.parseFloat(raw);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    // Warn rather than throw: this is read at the first span, not at boot, and a process that
+    // dies mid-request over a sampling typo has turned an observability misconfiguration into an
+    // outage. Falling back to 1 keeps the traces — losing them silently is the worse failure.
+    logger.warn('X_TELEMETRY_SAMPLER_ARG_INVALID', {
+      cause: `${spelling}="${raw}" is not a ratio between 0 and 1; sampling every trace instead`,
+      fix: `set ${spelling} to a value between 0 and 1, e.g. ${spelling}=0.05`,
+    });
+    return DEFAULT_SAMPLE_RATIO;
+  }
+  return parsed;
+}
+
+/**
+ * The sampler the env asks for. Recognises the OTel spellings an operator already knows; anything
+ * else falls through to parent-based ratio, which is the default behaviour either way.
+ */
+export function samplerFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): Sampler {
+  const name = (env[OTEL_SAMPLER_KEY] ?? '').trim().toLowerCase();
+  const ratio = readRatio(env[OTEL_SAMPLER_ARG_KEY], OTEL_SAMPLER_ARG_KEY);
+  switch (name) {
+    case 'always_off':
+      return alwaysOffSampler;
+    case 'always_on':
+      return alwaysOnSampler;
+    case 'traceidratio':
+      return ratioSampler(ratio);
+    case 'parentbased_always_off':
+      return parentBasedRatioSampler(0);
+    default:
+      // `parentbased_always_on`, `parentbased_traceidratio` and the unset case are one sampler:
+      // honour the parent, else the ratio — which is 1 when nothing set an arg.
+      return parentBasedRatioSampler(ratio);
+  }
+}
+
+let cached: Sampler | undefined;
+
+/**
+ * Read at the first span, never at module scope: `installSecrets()` and `defineEnv()` both land
+ * values in `process.env` during boot, and a module-scope read would pin whatever was set before
+ * the app configured itself — the same defect `cursor.ts` fixed by moving its secret read into
+ * `sign()`.
+ */
+export function defaultSampler(): Sampler {
+  if (cached === undefined) cached = samplerFromEnv();
+  return cached;
+}
+
+/** Test-only: forget the env-derived sampler so the next read sees the current environment. */
+export function resetDefaultSampler(): void {
+  cached = undefined;
+}

package/src/schema-error-codes.ts

@@ -0,0 +1,28 @@
+// Single responsibility: register `@ultimat3/schema`'s error codes so their titles render for any
+// process that imports `@ultimat3/core` — not just the CLI. `@ultimat3/schema` is tier 0 alongside
+// this package, so it cannot call `registerErrorCodes()` itself (that would mean importing core,
+// a same-tier import) and this package cannot import schema to read its declarations back (same
+// reason, the other direction). The codes below are a deliberate, tested duplicate of
+// `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts` — `schema-error-codes-pin.test.ts`, in a
+// package that may legally import both (`@ultimat3/cli`), asserts them equal so a title edited in
+// one place and not the other fails the build instead of quietly disagreeing at runtime.
+
+import { registerErrorCodes } from './error-codes';
+
+/** Mirrors `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts`. Keep the titles identical. */
+export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object.freeze({
+  X_VALIDATION_FAILED: 'value did not match its schema',
+  X_SCHEMA_UNSUPPORTED: 'the active schema provider cannot do this',
+  X_SCHEMA_DISCRIMINANT_INVALID: 'a discriminated union member can never be dispatched to',
+  X_SCHEMA_DEFAULT_UNSHAREABLE: 'a schema default cannot be copied per parse',
+});
+
+// Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because core does not own
+// these codes — `@ultimat3/schema` does — and `registerErrorCodes` is the one mechanism that
+// raises `X_ERROR_CODE_DUPLICATE` if a package that DOES own one of them ever tries to register it
+// too, which pins ownership even though the titles live in two files.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(SCHEMA_ERROR_CODE_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);

package/src/secrets-errors.ts

@@ -0,0 +1,143 @@
+// Single responsibility: the seven X_SECRETS_* conditions and the errors that carry them. Split
+// from `secrets.ts` so the crypto module reads as crypto — and there are seven codes rather than
+// one "secrets are broken" because each names a different thing an operator did and a different
+// command that undoes it. No error here ever carries a key, a ciphertext or a decrypted value.
+
+import { registerErrorCodes } from './error-codes';
+import { UltimateError } from './errors';
+
+/** Codes `@ultimat3/core` owns for the encrypted-secrets file. */
+export const SECRETS_ERROR_CODES = [
+  'X_SECRETS_KEY_MISSING',
+  'X_SECRETS_KEY_INVALID',
+  'X_SECRETS_KEY_MISMATCH',
+  'X_SECRETS_FILE_MISSING',
+  'X_SECRETS_FILE_INVALID',
+  'X_SECRETS_TAMPERED',
+  'X_SECRETS_PLAINTEXT_INVALID',
+] as const;
+
+export type SecretsErrorCode = (typeof SECRETS_ERROR_CODES)[number];
+
+const SECRETS_ERROR_TITLES: Readonly<Record<SecretsErrorCode, string>> = {
+  X_SECRETS_KEY_MISSING: 'no master key for the encrypted secrets file',
+  X_SECRETS_KEY_INVALID: 'the master key is not 32 bytes of hex',
+  X_SECRETS_KEY_MISMATCH: 'the secrets file was sealed with a different master key',
+  X_SECRETS_FILE_MISSING: 'the encrypted secrets file does not exist',
+  X_SECRETS_FILE_INVALID: 'the encrypted secrets file is not a readable envelope',
+  X_SECRETS_TAMPERED: 'the secrets file failed its authentication tag',
+  X_SECRETS_PLAINTEXT_INVALID: 'the decrypted secrets are not a flat map of env values',
+};
+
+// Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because these codes and the
+// module that throws them ship together: `registerErrorCodes` is the documented way a set of codes
+// joins the registry, and it raises `X_ERROR_CODE_DUPLICATE` if anything else ever claims one.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(SECRETS_ERROR_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);
+
+/**
+ * No key in the environment and none on disk, while an encrypted file exists. Deliberately fatal
+ * rather than a warning: booting without the secrets a deploy was configured with produces an app
+ * that authenticates against nothing and reports itself healthy.
+ */
+export class SecretsKeyMissingError extends UltimateError {
+  constructor(input: { envVar: string; keyPath: string }) {
+    super({
+      code: 'X_SECRETS_KEY_MISSING',
+      cause: `${input.envVar} is unset and ${input.keyPath} does not exist, so nothing can open the encrypted secrets`,
+      fix: `export ${input.envVar}="$(cat ${input.keyPath})"   # in a repo that has no key yet: x secrets init`,
+      meta: { keyPath: input.keyPath },
+    });
+  }
+}
+
+/** Key material that is not 64 lowercase hex characters. A truncated paste is the usual cause. */
+export class SecretsKeyInvalidError extends UltimateError {
+  constructor(input: { at: string; found: number; expected: number }) {
+    super({
+      code: 'X_SECRETS_KEY_INVALID',
+      cause: `the master key in ${input.at} is ${input.found} character(s); an AES-256 key is ${input.expected} lowercase hex characters`,
+      fix: `export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"   # the key file holds the ${input.expected} characters verbatim, no newline of its own`,
+      meta: { at: input.at },
+    });
+  }
+}
+
+/**
+ * A well-formed key that is not the one this file was sealed with. Distinguishable from tampering
+ * only because the envelope carries a key id — a domain-separated SHA-256 of the key, which is
+ * safe to commit and is what turns "it will not decrypt" into two different instructions.
+ */
+export class SecretsKeyMismatchError extends UltimateError {
+  constructor(input: { at: string; keyAt: string; sealedWith: string; found: string }) {
+    super({
+      code: 'X_SECRETS_KEY_MISMATCH',
+      cause: `${input.at} was sealed with master key ${input.sealedWith} and ${input.keyAt} holds ${input.found}`,
+      fix: `git checkout -- ${input.at}   # or point ULTIMATE_SECRETS_KEY at the key whose id is ${input.sealedWith}`,
+      meta: { at: input.at, sealedWith: input.sealedWith, found: input.found },
+    });
+  }
+}
+
+/** No encrypted file at all — this repo has never run `x secrets init`. */
+export class SecretsFileMissingError extends UltimateError {
+  constructor(input: { at: string }) {
+    super({
+      code: 'X_SECRETS_FILE_MISSING',
+      cause: `${input.at} does not exist, so this app declares no encrypted secrets`,
+      fix: 'x secrets init',
+      meta: { at: input.at },
+    });
+  }
+}
+
+/**
+ * The envelope itself will not parse: not JSON, an unknown version or algorithm, a header field
+ * that is not base64, or a body too short to hold a 16-byte tag. Separate from `X_SECRETS_TAMPERED`
+ * because nothing here got as far as authentication — this is a file a merge or an editor mangled.
+ */
+export class SecretsFileInvalidError extends UltimateError {
+  constructor(input: { at: string; reason: string }) {
+    super({
+      code: 'X_SECRETS_FILE_INVALID',
+      cause: `${input.at} ${input.reason}`,
+      fix: `git checkout -- ${input.at}   # this file is written only by x secrets, never by hand`,
+      meta: { at: input.at },
+    });
+  }
+}
+
+/**
+ * The AES-256-GCM tag rejected the ciphertext or the header bound into it as AAD. Under a key whose
+ * id already matched, that means the committed bytes changed after they were sealed — a bad merge,
+ * a partial write, or an edit. Silent garbage is the alternative this code exists to prevent.
+ */
+export class SecretsTamperedError extends UltimateError {
+  constructor(input: { at: string }) {
+    super({
+      code: 'X_SECRETS_TAMPERED',
+      cause: `the AES-256-GCM authentication tag rejected ${input.at}: the ciphertext or its header changed after it was sealed`,
+      fix: `git checkout -- ${input.at}   # then confirm the restored file opens: x secrets show --json`,
+      meta: { at: input.at },
+    });
+  }
+}
+
+/**
+ * Decryption succeeded and the payload is not what a secrets file holds. Reachable two ways: an
+ * `x secrets edit` buffer saved as something other than a flat object, and a value that is not a
+ * non-empty string. Both are refused BEFORE sealing, so a file that opens always installs.
+ */
+export class SecretsPlaintextInvalidError extends UltimateError {
+  constructor(input: { at: string; reason: string }) {
+    super({
+      code: 'X_SECRETS_PLAINTEXT_INVALID',
+      cause: `the secrets for ${input.at} ${input.reason}`,
+      fix: 'x secrets edit   # the buffer is one flat JSON object: {"SESSION_SECRET": "s3cr3t"} — env var names to non-empty strings',
+      meta: { at: input.at },
+    });
+  }
+}

package/src/secrets-store.ts

@@ -0,0 +1,173 @@
+// Single responsibility: where the two secrets files live, how the master key is found, and the
+// ONE path from a decrypted value to a `defineEnv`-declared variable — `installSecrets()` writes
+// each value into the process environment, under its own name, only where the real environment has
+// nothing. `secrets.ts` owns the envelope; this owns the filesystem and `process.env`.
+
+// `node:fs` sync, by necessity twice over: Bun.write takes no mode, and a world-readable master key
+// is the whole failure this file exists to prevent — and `installSecrets()` runs once, at boot,
+// before the process is serving anything, so there is nothing for an async read to overlap with.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+// Bun exposes no path-join primitive.
+import { join } from 'node:path';
+import type { SecretValues } from './secrets';
+import { masterKeyId, openSecrets, parseMasterKey, sealSecrets } from './secrets';
+import { SecretsFileMissingError, SecretsKeyMissingError } from './secrets-errors';
+
+/** Committed. Encrypted at rest, diffable, and the only file `x secrets` writes into the repo. */
+export const SECRETS_FILE = 'secrets.enc.json';
+/** Never committed — `x secrets init` writes the ignore rule before it writes this. */
+export const SECRETS_KEY_FILE = '.secrets.key';
+/** Read first, so a container gets its key from the platform's secret store and never from a file. */
+export const SECRETS_KEY_ENV = 'ULTIMATE_SECRETS_KEY';
+/** Owner read/write. A key file the rest of the box can read is a key file that has leaked. */
+export const SECRETS_KEY_MODE = 0o600;
+
+export type MasterKeySource = 'env' | 'file';
+
+export interface MasterKeyRef {
+  readonly hex: string;
+  readonly source: MasterKeySource;
+  /** The env var name or the file path, for an error's `cause` — never the key itself. */
+  readonly at: string;
+}
+
+type EnvRecord = Record<string, string | undefined>;
+
+export const secretsPath = (root: string): string => join(root, SECRETS_FILE);
+export const masterKeyPath = (root: string): string => join(root, SECRETS_KEY_FILE);
+export const secretsFileExists = (root: string): boolean => existsSync(secretsPath(root));
+
+/**
+ * Env var first, key file second. That order is what makes one image run everywhere: a container
+ * is handed `ULTIMATE_SECRETS_KEY` and never ships a key file, while a checkout has the file and
+ * needs no exported variable.
+ */
+export function findMasterKey(
+  root: string,
+  env: EnvRecord = process.env,
+): MasterKeyRef | undefined {
+  const fromEnv = env[SECRETS_KEY_ENV];
+  if (fromEnv !== undefined && fromEnv.trim().length > 0) {
+    return { hex: fromEnv.trim(), source: 'env', at: SECRETS_KEY_ENV };
+  }
+  const path = masterKeyPath(root);
+  if (!existsSync(path)) return undefined;
+  return { hex: readFileSync(path, 'utf-8').trim(), source: 'file', at: path };
+}
+
+export function requireMasterKey(root: string, env: EnvRecord = process.env): MasterKeyRef {
+  const found = findMasterKey(root, env);
+  if (found !== undefined) return found;
+  throw new SecretsKeyMissingError({ envVar: SECRETS_KEY_ENV, keyPath: masterKeyPath(root) });
+}
+
+/** The key's public id. Safe to print, safe to commit — it is what names a rotation in a diff. */
+export const masterKeyIdOf = (key: MasterKeyRef): Promise<string> =>
+  masterKeyId(parseMasterKey(key.hex, key.at));
+
+/** Decrypt the committed file. `X_SECRETS_FILE_MISSING` when there is none — never an empty map. */
+export async function readSecretsFile(root: string, key: MasterKeyRef): Promise<SecretValues> {
+  const path = secretsPath(root);
+  if (!existsSync(path)) throw new SecretsFileMissingError({ at: path });
+  return openSecrets(readFileSync(path, 'utf-8'), key.hex, { file: path, key: key.at });
+}
+
+/** Seal and commit. The only writer of `secrets.enc.json`; plaintext never reaches this path. */
+export async function writeSecretsFile(
+  root: string,
+  values: SecretValues,
+  key: MasterKeyRef,
+): Promise<string> {
+  const path = secretsPath(root);
+  await Bun.write(path, await sealSecrets(values, key.hex, { file: path, key: key.at }));
+  return path;
+}
+
+/** Write the master key at 0600. Callers must have made the ignore rule true first. */
+export function writeMasterKeyFile(root: string, keyHex: string): string {
+  const path = masterKeyPath(root);
+  writeFileSync(path, `${keyHex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE });
+  return path;
+}
+
+export interface SecretsInstallOptions {
+  /** The app root holding `secrets.enc.json`. Defaults to the process's working directory. */
+  readonly root?: string | undefined;
+  /** Read for the key and written with the values. Defaults to `process.env`. */
+  readonly env?: EnvRecord | undefined;
+}
+
+/** Names only. A report that carried a value would be a secret in every log that printed it. */
+export interface SecretsInstallReport {
+  readonly present: boolean;
+  readonly path: string;
+  readonly keySource: MasterKeySource | undefined;
+  readonly keyId: string | undefined;
+  /** Variables this call set. */
+  readonly installed: readonly string[];
+  /** Variables the real environment already supplied, so the file's value was not used. */
+  readonly skipped: readonly string[];
+}
+
+/**
+ * Decrypt the committed secrets into the environment, then let `defineEnv` do what it already does.
+ *
+ * ```ts
+ * await installSecrets();                                   // app.config.ts, first line
+ * export const envSchema = { SESSION_SECRET: { type: 'string', secret: true } } satisfies EnvSchema;
+ * export const env = defineEnv(envSchema);
+ * ```
+ *
+ * This is the whole integration, and it is one path rather than two on purpose. A secret has one
+ * name — the env var it becomes — so it keeps one declaration (`envSchema`), one row in
+ * `.env.example`, one masker (`maskedEnvValues`), one redaction entry (`redactKeys`) and one
+ * reader (`env.SESSION_SECRET`). A `secrets.get('…')` accessor would mint values with no
+ * declaration, no type and no mask, and every one of those five would need a second implementation.
+ *
+ * The real environment always wins: a platform-injected `DATABASE_URL` beats the committed file, so
+ * the same image runs in Compose and K8s without a second secrets file per deploy. A file that does
+ * not exist is not an error — an app may declare no secrets — but a file that exists with no key to
+ * open it is `X_SECRETS_KEY_MISSING`, because booting past it produces an app that authenticates
+ * against nothing and reports itself healthy.
+ *
+ * Forgetting the `await` fails loudly rather than silently: `defineEnv` runs first and throws
+ * `X_ENV_MISSING` naming every variable the file would have supplied.
+ */
+export async function installSecrets(
+  options: SecretsInstallOptions = {},
+): Promise<SecretsInstallReport> {
+  const root = options.root ?? process.cwd();
+  const env = options.env ?? (process.env as EnvRecord);
+  const path = secretsPath(root);
+  if (!existsSync(path)) {
+    return {
+      present: false,
+      path,
+      keySource: undefined,
+      keyId: undefined,
+      installed: [],
+      skipped: [],
+    };
+  }
+  const key = requireMasterKey(root, env);
+  const values = await readSecretsFile(root, key);
+  const installed: string[] = [];
+  const skipped: string[] = [];
+  for (const [name, value] of Object.entries(values)) {
+    const current = env[name];
+    if (current === undefined || current === '') {
+      env[name] = value;
+      installed.push(name);
+    } else {
+      skipped.push(name);
+    }
+  }
+  return {
+    present: true,
+    path,
+    keySource: key.source,
+    keyId: await masterKeyIdOf(key),
+    installed: installed.sort(),
+    skipped: skipped.sort(),
+  };
+}