@voxgig/station 0.0.1

package/src/loader.ts

@@ -0,0 +1,188 @@
+/* The loader (design §6.3), where the language allows it.
+ *
+ * In ts, js, py, rb, php, perl, lua, elixir and clojure a module can be
+ * imported by name at runtime, so `api.<slug>.package` closes the loop:
+ * station imports the package (which triggers self-registration, §6.2
+ * path 1) and then looks up the factory.
+ *
+ * `sdk()` IS SYNCHRONOUS, AND IN TS/JS THAT BOUNDS WHAT THE LOADER CAN
+ * IMPORT. A CommonJS package loads synchronously through `require`; an
+ * ESM-only package only loads through `import()`, which is a promise.
+ * Making `sdk()` async to cover that would put an `await` in front of
+ * every call site in every language for a cost only two of them pay.
+ * So the rule is explicit rather than discovered at runtime:
+ *
+ *  - the synchronous loader handles CommonJS, which is every SDK sdkgen
+ *    generates (the ts target is `"type": "commonjs"`);
+ *  - ESM packages load through an explicit `await station.load()`
+ *    preload, after which `sdk()` is synchronous again for everything —
+ *    one `await` at startup rather than one per call site;
+ *  - a package only `import()` can load, reached through `sdk()`
+ *    without a preload, is `station_sdk_load` WITH THE REMEDY IN THE
+ *    MESSAGE. Never a silent half-loaded client.
+ *
+ * THIS IS A CODE-LOADING SURFACE DRIVEN BY A CONFIG FILE, so it has
+ * rules, and they are enforced here rather than documented and hoped
+ * for. See `checkPackage` and the `repoScoped` argument. */
+
+import { StationError } from './error'
+import { Factory, factoryFor, provide } from './factory'
+
+/** The fixed alias every generated package exports.
+ *
+ * `export` defaults to this rather than to a derived class name because
+ * it is the same identifier in every generated package, where
+ * `camelify(slug) + 'SDK'` is a rule that has to be recomputed and can
+ * be wrong. The derived name is the SECOND attempt and an explicit
+ * `export` the third. */
+export const DEFAULT_EXPORT = 'SDK'
+
+/** `stripe-eu` -> `StripeEu`, for the second-attempt export name. */
+export function camelify(slug: string): string {
+  return String(slug).split(/[^A-Za-z0-9]+/).filter((s) => '' !== s)
+    .map((s) => s[0].toUpperCase() + s.slice(1))
+    .join('')
+}
+
+/** Only MODULE NAMES, resolved by the host language's ordinary
+ * resolution from the application root. Never a filesystem path, never
+ * a URL, never anything relative — a config file naming a path is a
+ * config file reaching outside the dependency graph it is allowed to
+ * name. */
+export function checkPackage(api: string, pkg: string): string {
+  const p = String(pkg)
+  // A TRAVERSAL SEGMENT IS NOT A LEADING MARKER, and checking only the
+  // first character missed it: `pkg/../../escape` starts with neither
+  // `.` nor `/`, so it passed — and node resolves it through
+  // `node_modules/pkg/../../escape`, importing application-local code
+  // from outside the named dependency. The whole point of this function
+  // is that a configured package stays inside the dependency graph a
+  // reviewer can see.
+  const seg = p.split('/').some((x) => '.' === x || '..' === x)
+  const bad =
+    '' === p ||
+    p.startsWith('.') ||
+    p.startsWith('/') ||
+    p.startsWith('~') ||
+    seg ||
+    -1 !== p.indexOf('://') ||
+    -1 !== p.indexOf('\\')
+  if (bad) {
+    throw new StationError('station_sdk_load',
+      'api "' + api + '": `package` must be a module name resolved from ' +
+      'the application root, not a path or URL: ' + JSON.stringify(pkg))
+  }
+  return p
+}
+
+/** Build a `{construct, config}` pair from a module that self-registered
+ * nothing — the retrofit path for a package whose SDK predates the
+ * station feature. It is not descriptor-blind: a generated main module
+ * exports its constructor AND the `config` singleton beside it. */
+export function factoryFromModule(
+  api: string, mod: any, exportName?: string
+): Factory {
+  const tried: string[] = []
+  const pick = (n: string): any => {
+    tried.push(n)
+    return null == mod ? undefined : mod[n]
+  }
+
+  let ctor = null == exportName || '' === exportName
+    ? undefined : pick(exportName)
+  if (null == ctor) { ctor = pick(DEFAULT_EXPORT) }
+  if (null == ctor) { ctor = pick(camelify(api) + 'SDK') }
+
+  if ('function' !== typeof ctor) {
+    throw new StationError('station_sdk_load',
+      'api "' + api + '": no SDK constructor found on the module; tried [' +
+      tried.join(', ') + ']. Set `export` to the exported name.')
+  }
+
+  const config = mod.config ?? mod.CONFIG
+  if (null == config) {
+    throw new StationError('station_sdk_load',
+      'api "' + api + '": the module exports a constructor but no `config` ' +
+      'singleton, so its feature schema and transport roles cannot be read ' +
+      'before construction (§6.2)')
+  }
+
+  const construct = (options: any) => new (ctor as any)(options)
+  return { construct, config }
+}
+
+/** Synchronous load, for CommonJS. Returns true when the api has a
+ * factory afterwards — either because importing the package triggered
+ * self-registration, or because one was built from its exports. */
+export function loadSync(api: string, pkg: string, exportName?: string): boolean {
+  checkPackage(api, pkg)
+  if (null != factoryFor(api)) { return true }
+
+  let mod: any
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    mod = require(pkg)
+  }
+  catch (e: any) {
+    // ERR_REQUIRE_ESM is the case the preload exists for, and the
+    // message has to name the remedy rather than the symptom.
+    const code = String(e?.code || '')
+    if ('ERR_REQUIRE_ESM' === code) {
+      throw new StationError('station_sdk_load',
+        'api "' + api + '": package "' + pkg + '" is ESM-only and cannot be ' +
+        'loaded synchronously; `await station.load()` at startup, then ' +
+        'sdk() is synchronous again for everything (§6.3)')
+    }
+    throw new StationError('station_sdk_load',
+      'api "' + api + '": package "' + pkg + '" could not be imported: ' +
+      String(e?.message || e))
+  }
+
+  // Path 1: the module self-registered while being imported.
+  if (null != factoryFor(api)) { return true }
+
+  provide(api, factoryFromModule(api, mod, exportName))
+  return true
+}
+
+/** The ESM preload behind `await station.load()`. Imports the package
+ * and fills the SAME table the synchronous path fills. */
+/** A dynamic `import()` that SURVIVES THE COMMONJS EMIT.
+ *
+ * This package compiles with `module: "commonjs"`, and TypeScript
+ * rewrites a literal `import(pkg)` into a promise around `require(pkg)`
+ * — so `await station.load()` threw `ERR_REQUIRE_ESM` for exactly the
+ * ESM-only packages it exists to preload, leaving no working path to
+ * those SDKs at all. Verified against the emitted `dist/src/loader.js`,
+ * which read `mod = require(pkg)`.
+ *
+ * `new Function` is the seam the compiler does not look inside. It is
+ * deliberately the only one in this file, and it takes no caller input:
+ * `pkg` has already been through `checkPackage`, and the body is a
+ * constant. Changing the package to `module: "node16"` would fix it
+ * more cleanly and is a whole-package decision rather than a defect
+ * fix. */
+export const nativeImport: (p: string) => Promise<any> =
+  new Function('p', 'return import(p)') as any
+
+export async function loadAsync(
+  api: string, pkg: string, exportName?: string
+): Promise<boolean> {
+  checkPackage(api, pkg)
+  if (null != factoryFor(api)) { return true }
+
+  let mod: any
+  try { mod = await nativeImport(pkg) }
+  catch (e: any) {
+    throw new StationError('station_sdk_load',
+      'api "' + api + '": package "' + pkg + '" could not be imported: ' +
+      String(e?.message || e))
+  }
+
+  if (null != factoryFor(api)) { return true }
+
+  // An ESM namespace puts a CommonJS module's exports under `default`.
+  const flat = null != mod?.default && null == mod?.config ? mod.default : mod
+  provide(api, factoryFromModule(api, flat, exportName))
+  return true
+}

package/src/profile.ts

@@ -0,0 +1,67 @@
+/* The FILE half of profile handling - finding and reading
+ * station.json - and the scope rule that hangs off where it was found.
+ * NODE-ONLY by construction (fs/os/path), which is the §2.2 / §17
+ * Phase 1 split: the browser entry never imports this module, and
+ * `Station` reaches it through the ConfigFileIO seam the node entry
+ * registers. The pure half (selectProfile, refapi, resolveProfile)
+ * lives in `profilecore.ts` and is re-exported here so every existing
+ * import of `./profile` keeps working. */
+
+import Fs from 'node:fs'
+import Os from 'node:os'
+import Path from 'node:path'
+
+import { StationError } from './error'
+import { StationConfig } from './types'
+
+export {
+  refapi, resolveProfile, selectProfile,
+} from './profilecore'
+export type { ResolvedProfile } from './profilecore'
+
+// station.json lookup: cwd upward to the repo root, then
+// ~/.voxgig/station.json (design §3.5). A repo root is where .git lives;
+// with no repo the walk stops at the filesystem root.
+export function findConfigFile(from?: string): string | null {
+  let dir = Path.resolve(from || process.cwd())
+  for (; ;) {
+    const candidate = Path.join(dir, 'station.json')
+    if (Fs.existsSync(candidate)) { return candidate }
+    const atRepoRoot = Fs.existsSync(Path.join(dir, '.git'))
+    const parent = Path.dirname(dir)
+    if (atRepoRoot || parent === dir) { break }
+    dir = parent
+  }
+  const home = Path.join(Os.homedir(), '.voxgig', 'station.json')
+  return Fs.existsSync(home) ? home : null
+}
+
+export function loadConfig(from?: string): StationConfig | null {
+  const file = findConfigFile(from)
+  if (null == file) { return null }
+  const text = Fs.readFileSync(file, 'utf8')
+  // A file that is not JSON is a config error, not a raw SyntaxError
+  // escaping open(): the reader found station.json and could not use
+  // it, which is exactly what station_config_invalid exists to say.
+  try {
+    return JSON.parse(text)
+  }
+  catch (err: any) {
+    throw new StationError('station_config_invalid',
+      'station.json at ' + file + ' is not valid JSON: ' + err.message)
+  }
+}
+
+// Which side of the review boundary the config came from (§6.3).
+//
+// `package` and `export` are honoured only from REPO-SCOPED config,
+// because a user-level file is outside the repo's review boundary and a
+// `package` key arriving from it names code to import. Everything else
+// in a user-level config still applies - this narrows one key rather
+// than distrusting the file.
+export function configScope(from?: string): 'repo' | 'user' | 'none' {
+  const file = findConfigFile(from)
+  if (null == file) { return 'none' }
+  const home = Path.join(Os.homedir(), '.voxgig', 'station.json')
+  return file === home ? 'user' : 'repo'
+}

package/src/profilecore.ts

@@ -0,0 +1,201 @@
+/* The pure half of profile handling: selection, the ref grammar, and
+ * the §3.3 merge. Split from `profile.ts` so the BROWSER ENTRY can
+ * reach it (§2.2, §17 Phase 1): everything here is data-in/data-out,
+ * while the file half (findConfigFile/loadConfig/configScope) is
+ * node-only and stays in `profile.ts`, imported by the node entry
+ * alone. `profile.ts` re-exports these, so every existing import path
+ * is unchanged. */
+
+import { validname } from '@voxgig/sekreto'
+
+import { secretnameDefault } from './descriptor'
+import { StationError } from './error'
+import { BLOCK_DEFAULTS } from './shape'
+import { StationConfig, SdkBlock } from './types'
+
+// Profile selection: VOXGIG_STATION_PROFILE, else the open() option,
+// else 'default' (design §3.5 - env vars rank above station.json but
+// below open() opts; profile NAME selection follows the same order with
+// open() opts winning).
+//
+// `process` is reached through a typeof guard rather than an import:
+// in the browser there is no process and no environment, so the answer
+// is simply the option or the default - which is the same degradation
+// "no env var set" already means.
+export function selectProfile(optProfile?: string): string {
+  if (null != optProfile && '' !== optProfile) { return optProfile }
+  const env = 'undefined' !== typeof process
+    ? process.env.VOXGIG_STATION_PROFILE : undefined
+  if (null != env && '' !== env) { return env }
+  return 'default'
+}
+
+// The api half of a ref is the substring before the first `$`, and an
+// untagged ref IS an api slug (design §3.4) - which is why the whole
+// `plugin` -> `sdk` migration is a key rename and nothing else.
+//
+// LEXICAL, and that is the point: under the old free-form identity
+// which api an instance used was itself a merged value, so the merge
+// could not be a flat pass over both maps and a port that got the
+// phasing wrong silently picked another api's defaults (§3.3).
+export function refapi(ref: string): string {
+  const at = String(ref).indexOf('$')
+  return -1 === at ? String(ref) : String(ref).slice(0, at)
+}
+
+export type ResolvedProfile = {
+  name: string
+  providers: any[]
+  // The api-level defaults in effect for this profile, base ⊕ overlay
+  // per api slug. A REPORT, not an input to the instance merge below -
+  // collapsing each namespace first and composing at the end is the
+  // exact algorithm §3.3 forbids.
+  api: Record<string, SdkBlock>
+  // Instances, keyed by ref. An `api` block declares no instance of its
+  // own (§3.1), so it never creates an entry here.
+  sdk: Record<string, SdkBlock>
+}
+
+// Shallow merge, per key, left to right - each source over the one
+// before it. Declared rather than assumed: plugin's library default is
+// a deep map merge, and an allowlist that widens because two precedence
+// levels merged is the failure this rule exists to prevent
+// (station-and-plugin.md §2.5). The visible consequence: an overlay's
+// `policy` REPLACES the base's entirely rather than merging `hosts`
+// into it. That is also the safer reading for an allowlist.
+function shallow(...sources: any[]): any {
+  const out: any = {}
+  for (const src of sources) {
+    if (null == src || 'object' !== typeof src || Array.isArray(src)) { continue }
+    for (const k of Object.keys(src)) { out[k] = src[k] }
+  }
+  return out
+}
+
+// Merge the base profile ('default') with the selected overlay.
+//
+// §3.3's total order, for the two block levels - lowest precedence
+// first:
+//
+//   base.api[<api>] ⊕ base.sdk[<ref>] ⊕ overlay.api[<api>] ⊕ overlay.sdk[<ref>]
+//
+// PROFILE SPECIFICITY OUTRANKS BLOCK SPECIFICITY. A `prod` api-level
+// `base` beats a `default` instance-level `base`, because that is what
+// an environment overlay is for; within one profile the instance beats
+// the api default, because that is what an instance is for.
+//
+// THIS IS ONE FLAT LEFT-TO-RIGHT MERGE AND MUST NOT BE REORGANIZED INTO
+// "collapse each namespace, then put instance over api". Collapsing
+// first computes (base.api ⊕ overlay.api) and (base.sdk ⊕ overlay.sdk)
+// and then lets EVERY instance value beat EVERY api value - the exact
+// opposite. A production `api.stripe.policy` would then fail to
+// override a default profile's `sdk.stripe$test.policy`, silently
+// keeping the wider allowlist in production.
+//
+// `secrets.providers` replaces wholesale, never merges (§3.5, §5.2):
+// chain order decides which store wins, so a positional merge would be
+// actively dangerous.
+export function resolveProfile(
+  config: StationConfig | null, profileName: string
+): ResolvedProfile {
+  const profiles = config?.profiles || {}
+  const base: any = profiles['default'] || {}
+  const overlay: any = 'default' === profileName
+    ? {} : (profiles[profileName] || {})
+
+  const providers = overlay.secrets?.providers ?? base.secrets?.providers ??
+    [{ kind: 'env' }]
+
+  const api: Record<string, SdkBlock> = {}
+  for (const slug of sortedkeys(base.api, overlay.api)) {
+    api[slug] = shallow(base.api?.[slug], overlay.api?.[slug])
+  }
+
+  // An api block declares no instance, so the ref set comes from the
+  // two `sdk` maps alone.
+  const sdk: Record<string, SdkBlock> = {}
+  for (const ref of sortedkeys(base.sdk, overlay.sdk)) {
+    const a = refapi(ref)
+    const merged = shallow(
+      base.api?.[a],
+      base.sdk?.[ref],
+      overlay.api?.[a],
+      overlay.sdk?.[ref],
+    )
+
+    // Defaults are applied ONCE, to the fully merged instance, and this
+    // is the rule §4.2's normalization must not be confused with. Had
+    // the overlay block carried a synthesized `active: true` into the
+    // merge, a one-key environment override would silently re-enable an
+    // integration the base declared `active: false` - live in
+    // production despite being declared inactive. The `instance` corpus
+    // section carries exactly this case.
+    for (const k of Object.keys(BLOCK_DEFAULTS)) {
+      if (undefined === merged[k]) { merged[k] = BLOCK_DEFAULTS[k]() }
+    }
+
+    sdk[ref] = merged
+  }
+
+  checksecrets(sdk, profileName)
+
+  return { name: profileName, providers, api, sdk }
+}
+
+// A configured secret name sekreto would reject is caught at profile
+// load, not first request (§14 station_secret_name) - and then the
+// derived names are checked for uniqueness, because envtoken is LOSSY.
+//
+// It collapses any run of non-alphanumerics to `_`, so `$` and `-` are
+// indistinguishable downstream: the ref `stripe$test` and an untagged
+// instance of an api slugged `stripe-test` both derive
+// `stripe_test.apikey`. That pairing is the realistic one rather than a
+// contrived one, because api slugs are hyphenated by construction - so
+// a fleet with both a `stripe-test` api and a `test` instance of
+// `stripe` collides by default. Since the resolution cache is keyed by
+// secret name (§5.3), the second instance would silently receive the
+// first's value.
+//
+// Two instances that EXPLICITLY name the same secret are not a
+// collision - that is the shared-key case the api-level `secret` exists
+// for, and saying so out loud is how you ask for it.
+function checksecrets(
+  sdk: Record<string, SdkBlock>, profileName: string
+): void {
+  const refs = Object.keys(sdk).sort()
+
+  for (const ref of refs) {
+    const name = sdk[ref].secret
+    if (null != name && !validname(name)) {
+      throw new StationError('station_secret_name',
+        'profile "' + profileName + '" sdk "' + ref +
+        '": secret name rejected by sekreto: ' + JSON.stringify(name))
+    }
+  }
+
+  const seen = new Map<string, { ref: string, derived: boolean }>()
+  for (const ref of refs) {
+    const written = sdk[ref].secret
+    const derived = null == written || '' === written
+    const name = derived ? secretnameDefault(ref) : (written as string)
+
+    const prior = seen.get(name)
+    if (undefined !== prior && (derived || prior.derived)) {
+      throw new StationError('station_secret_collision',
+        'profile "' + profileName + '": instances "' + prior.ref + '" and "' +
+        ref + '" both resolve to secret name "' + name +
+        '", so they would share one credential; name it explicitly on ' +
+        'each, or at the api level to share it deliberately (§5.1)')
+    }
+    if (undefined === prior) { seen.set(name, { ref, derived }) }
+  }
+}
+
+function sortedkeys(...maps: any[]): string[] {
+  const keys = new Set<string>()
+  for (const m of maps) {
+    if (null == m || 'object' !== typeof m || Array.isArray(m)) { continue }
+    for (const k of Object.keys(m)) { keys.add(k) }
+  }
+  return Array.from(keys).sort()
+}

package/src/secrets.ts

@@ -0,0 +1,96 @@
+import { Sekreto, SekretoError } from '@voxgig/sekreto'
+
+import { StationError } from './error'
+
+// The secret broker (design §5): sekreto resolves, station places. The
+// broker holds resolved values privately - they never enter options,
+// events, or captures; the SDK sees only the placeholder.
+
+// §7.2: keyed by INSTANCE. Two live instances of one api must have
+// distinct placeholders or the injection seam cannot tell which
+// credential a header wants. For an untagged instance this is the api
+// slug, so the single-instance case is unchanged.
+export function placeholderFor(slug: string): string {
+  return '[station:' + slug + ']'
+}
+
+export class SecretBroker {
+  private sekreto: Sekreto
+  // Values hoisted by adopt() from resident options.apikey (design §3.1).
+  private overrides = new Map<string, string>()
+  private cache = new Map<string, string>()
+  // Every value this broker ever held, for the exact-value scrub.
+  private held: string[] = []
+
+  constructor(providers: any[]) {
+    this.sekreto = new Sekreto({ providers })
+  }
+
+  hoist(slug: string, value: string): void {
+    this.overrides.set(slug, value)
+    this.held.push(value)
+  }
+
+  // Resolve the value for a plugin's secret name. Misses and store
+  // errors keep sekreto's distinction (design §5.2): a miss is
+  // station_secret_no_value, a store that could not answer is
+  // station_secret_error with sekreto's message intact - and never a
+  // retry against a weaker store (sekreto owns the chain).
+  // OVERRIDES ARE KEYED BY INSTANCE; THE RESOLUTION CACHE IS KEYED BY
+  // SECRET NAME (§5.3). A hoisted credential belongs to the one instance
+  // it was resident in, but a resolved VALUE belongs to the name it was
+  // resolved for - so several instances sharing one api-level `secret`
+  // cost one lookup rather than one each, and every client an
+  // auto-tagged `create()` produces shares the declared instance's entry
+  // instead of re-resolving per request.
+  //
+  // Keying the cache by instance instead is the defect this replaces: at
+  // 26 instances over 20 apis it turns one store round-trip into 26.
+  async value(slug: string, name: string): Promise<string> {
+    const override = this.overrides.get(slug)
+    if (null != override) { return override }
+
+    const cached = this.cache.get(name)
+    if (null != cached) { return cached }
+
+    let value: string
+    try {
+      value = await this.sekreto.get(name)
+    }
+    catch (e: any) {
+      if (e instanceof SekretoError && e.message.includes('unknown secret')) {
+        throw new StationError('station_secret_no_value',
+          'no store had "' + name + '" for plugin "' + slug + '"')
+      }
+      throw new StationError('station_secret_error', String(e?.message || e))
+    }
+
+    this.cache.set(name, value)
+    this.held.push(value)
+    return value
+  }
+
+  // Exact-value scrub, deliberately WITHOUT sekreto's four-character
+  // readability floor (design §7 as revised): on boundaries where the
+  // promise is absolute, every held value is scrubbed whatever its
+  // length. sekreto's own redact() runs too, covering values resolved
+  // by the underlying instance that station never held.
+  scrub(text: string): string {
+    let out = this.sekreto.redact(text)
+    for (const value of this.held) {
+      if ('' !== value) {
+        out = out.split(value).join('[redacted]')
+      }
+    }
+    return out
+  }
+
+  // Drop caches so the next resolve asks the stores again (rotation
+  // support rides on sekreto's refresh, design §5.3).
+  refresh(): void {
+    this.cache.clear()
+    if ('function' === typeof (this.sekreto as any).refresh) {
+      ;(this.sekreto as any).refresh()
+    }
+  }
+}