@voxgig/sdkgen 4.5.3 → 4.7.0

package/project/.sdk/tm/ts/src/feature/secrets/sekreto/Sekreto.ts

@@ -0,0 +1,387 @@
+// VENDORED: @voxgig/sekreto 0.1.2 (typescript/src/Sekreto.ts)
+// Source: https://github.com/voxgig/sekreto @ 65009cb5758850db767785ab666e71895f86086b
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// sekreto: one interface for secrets, wherever they live.
+//
+// A Sekreto is an ordered chain of providers. `get` asks each in turn and
+// returns the first hit, so an app can be configured from environment
+// variables in development and a vault in production without changing a
+// line of its own code.
+//
+// This file is CANONICAL. Every other port is a translation of it, and
+// spec/sekreto.json is the behavioural contract they all run.
+
+// The REGISTRY, never './Providers'. Importing the barrel here is what
+// made every provider kind reachable from the core: the chain needs
+// `makeprovider`, and the barrel's edge dragged AWS request signing and
+// seven HTTP clients in behind it. The registry knows only the kinds
+// something actually imported. See docs/design/plugin-providers.md.
+import { Provider, ProviderSpec } from './provider/support'
+import { makeprovider } from './provider/Registry'
+
+/** A secret name: dot-separated lowercase segments, e.g. `api.token`. */
+export type Name = string
+
+export type SekretoOptions = {
+  /** The provider chain, in resolution order. */
+  providers?: (Provider | ProviderSpec)[]
+  /** Cache resolved values (default: true). */
+  cache?: boolean
+}
+
+/** Anything sekreto refuses to do: a bad name, a missing secret, a
+ * provider that could not be reached. */
+export class SekretoError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SekretoError'
+  }
+}
+
+const NAMEPART = /^[a-z0-9_]+$/
+
+/** Is this a well-formed secret name? */
+export function validname(name: any): boolean {
+  if ('string' !== typeof name || 0 === name.length) {
+    return false
+  }
+
+  const parts = name.split('.')
+
+  for (const part of parts) {
+    if (!NAMEPART.test(part)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+export function checkname(name: any): string {
+  if (!validname(name)) {
+    throw new SekretoError('sekreto: invalid name: ' + String(null == name ? '' : name))
+  }
+  return name
+}
+
+/** The environment-variable key for a name: `api.token` -> `API_TOKEN`. */
+export function envkey(name: Name, prefix?: string): string {
+  checkname(name)
+  return (prefix || '') + name.split('.').join('_').toUpperCase()
+}
+
+/** Where a name lives in a KV vault: `api.token` -> `api` / `token`.
+ *
+ * A single-segment name has no path of its own, so it becomes a secret of
+ * that name with the conventional field `value`. */
+export function vaultref(name: Name): { path: string; field: string } {
+  checkname(name)
+
+  const parts = name.split('.')
+
+  if (1 === parts.length) {
+    return { path: parts[0], field: 'value' }
+  }
+
+  return { path: parts.slice(0, -1).join('/'), field: parts[parts.length - 1] }
+}
+
+/** A name flattened to one segment: `api.token` -> `api_token` (GCP
+ * Secret Manager, `_`) or `api-token` (Azure Key Vault, `-`).
+ *
+ * Those stores have no path hierarchy and reject dots in ids, so the
+ * dots become the store's conventional separator. With `-` as the
+ * separator, underscores flatten too: Azure Key Vault's alphabet is
+ * letters, digits and hyphens only, and a valid sekreto name like
+ * `with_underscore` must still be representable there. (The resulting
+ * `.`/`_` collision mirrors the documented envkey behaviour, where
+ * both already map to `_`.) */
+export function flatname(name: Name, sep: string): string {
+  checkname(name)
+  const flat = name.split('.').join(sep)
+  return '-' === sep ? flat.split('_').join('-') : flat
+}
+
+/** The AWS SSM Parameter Store name for a name: dots become the path
+ * hierarchy, rooted at `/` (or at a prefix): `db.pass.main` ->
+ * `/db/pass/main`, or `/app/db/pass/main` under prefix `/app`. */
+export function awsparam(name: Name, prefix?: string): string {
+  checkname(name)
+
+  let base = prefix || ''
+  if ('' !== base && !base.startsWith('/')) {
+    base = '/' + base
+  }
+  base = base.replace(/\/$/, '')
+
+  return base + '/' + name.split('.').join('/')
+}
+
+/** Parse `.env` text into a map of raw keys to values.
+ *
+ * Deliberately small: `KEY=value`, optional `export`, `#` comments on their
+ * own line, and single- or double-quoted values (double quotes also
+ * unescape `\n`, `\r`, `\t` and `\\`). A line with no `=` is skipped. */
+export function parsedotenv(text: string): Record<string, string> {
+  const out: Record<string, string> = {}
+
+  if ('string' !== typeof text) {
+    return out
+  }
+
+  for (const rawline of text.split('\n')) {
+    const line = rawline.replace(/\r$/, '').trim()
+
+    if (0 === line.length || line.startsWith('#')) {
+      continue
+    }
+
+    const body = line.startsWith('export ') ? line.slice(7).trim() : line
+
+    const eq = body.indexOf('=')
+    if (0 >= eq) {
+      continue
+    }
+
+    const key = body.slice(0, eq).trim()
+    let value = body.slice(eq + 1).trim()
+
+    if (2 <= value.length && value.startsWith('"') && value.endsWith('"')) {
+      value = unescape(value.slice(1, -1))
+    } else if (2 <= value.length && value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1)
+    }
+
+    out[key] = value
+  }
+
+  return out
+}
+
+function unescape(text: string): string {
+  let out = ''
+
+  for (let index = 0; index < text.length; index++) {
+    if ('\\' === text[index] && index + 1 < text.length) {
+      const next = text[index + 1]
+      index++
+      if ('n' === next) {
+        out += '\n'
+      } else if ('r' === next) {
+        out += '\r'
+      } else if ('t' === next) {
+        out += '\t'
+      } else if ('\\' === next) {
+        out += '\\'
+      } else if ('"' === next) {
+        out += '"'
+      } else {
+        out += '\\' + next
+      }
+    } else {
+      out += text[index]
+    }
+  }
+
+  return out
+}
+
+/** Replace known secret values in text with `[redacted]`.
+ *
+ * Only values of four characters or more are replaced: shorter ones are
+ * too likely to appear in ordinary text, and redacting them would make
+ * logs unreadable without making them safer. */
+export function redact(text: string, values: string[]): string {
+  let out = 'string' === typeof text ? text : ''
+
+  for (const value of values || []) {
+    if ('string' !== typeof value || 4 > value.length) {
+      continue
+    }
+    out = out.split(value).join('[redacted]')
+  }
+
+  return out
+}
+
+/** One provider in the chain, under the store name it answers to. */
+type Entry = { store: string; provider: Provider }
+
+/** One resolved value. Kept as a list rather than a map so that the store
+ * a value came from stays attached, and so redaction order is stable. */
+type Cached = { store: string; name: Name; value: string }
+
+/** The store name a provider answers to when its spec does not say.
+ *
+ * `describe()` opens with the provider's kind - `vault:...`, `dotenv:...`,
+ * plain `env` - so the kind is the natural default, and a custom provider
+ * gets a sensible name without having to implement anything extra. */
+function storename(provider: Provider, spec?: ProviderSpec): string {
+  if (spec && spec.name) {
+    return spec.name
+  }
+  return provider.describe().split(':')[0]
+}
+
+/** The secrets facade: a chain of providers plus a cache.
+ *
+ * Two ways to read. `get` is transparent - it walks the chain and takes
+ * the first hit, and the caller never learns which store answered. `getfrom`
+ * is directed - it names the store, and only that store is asked. Use the
+ * first for ordinary configuration, the second when *which* store holds a
+ * secret is part of what you mean. */
+export class Sekreto {
+  private entries: Entry[]
+  private docache: boolean
+  private cache: Cached[]
+  // Every value ever resolved, for redact(). Kept independently of the
+  // read cache so that redaction still works when cache is off - otherwise
+  // `cache: false` would silently disable redact() and leak secrets to logs.
+  private seen: string[]
+
+  constructor(options?: SekretoOptions) {
+    const opts = options || {}
+
+    this.entries = (opts.providers || []).map((entry) => {
+      if ('function' === typeof (entry as Provider).lookup) {
+        const provider = entry as Provider
+        return { store: storename(provider), provider }
+      }
+
+      const spec = entry as ProviderSpec
+      const provider = makeprovider(spec)
+      return { store: storename(provider, spec), provider }
+    })
+
+    this.docache = false === opts.cache ? false : true
+    this.cache = []
+    this.seen = []
+  }
+
+  /** The secret, or a SekretoError if no provider has it. */
+  async get(name: Name): Promise<string> {
+    const found = await this.try(name)
+
+    if (undefined === found) {
+      throw new SekretoError('sekreto: unknown secret: ' + name)
+    }
+
+    return found
+  }
+
+  /** The secret, or undefined if no provider has it. */
+  async try(name: Name): Promise<string | undefined> {
+    return this.resolve('', name, this.entries)
+  }
+
+  /** The secret from one named store, or a SekretoError if that store does
+   * not have it. */
+  async getfrom(store: string, name: Name): Promise<string> {
+    const found = await this.tryfrom(store, name)
+
+    if (undefined === found) {
+      throw new SekretoError('sekreto: unknown secret: ' + store + ':' + name)
+    }
+
+    return found
+  }
+
+  /** The secret from one named store, or undefined if that store does not
+   * have it.
+   *
+   * Naming a store that is not in the chain is an error, not a miss: `try`
+   * already means "this store may not have it", so it cannot also mean
+   * "this store may not exist" without hiding a typo. */
+  async tryfrom(store: string, name: Name): Promise<string | undefined> {
+    const matching = this.entries.filter((entry) => entry.store === store)
+
+    if (0 === matching.length) {
+      throw new SekretoError('sekreto: unknown store: ' + store)
+    }
+
+    return this.resolve(store, name, matching)
+  }
+
+  private async resolve(store: string, name: Name, entries: Entry[]): Promise<string | undefined> {
+    checkname(name)
+
+    if (this.docache) {
+      const hit = this.cache.find((entry) => entry.store === store && entry.name === name)
+      if (undefined !== hit) {
+        return hit.value
+      }
+    }
+
+    for (const entry of entries) {
+      const found = await entry.provider.lookup(name)
+
+      if (undefined !== found && null !== found) {
+        if (this.docache) {
+          this.cache.push({ store, name, value: found })
+        }
+        this.seen.push(found)
+        return found
+      }
+    }
+
+    return undefined
+  }
+
+  /** Does any provider have this secret? */
+  async has(name: Name): Promise<boolean> {
+    return undefined !== (await this.try(name))
+  }
+
+  /** Does this named store have this secret? */
+  async hasin(store: string, name: Name): Promise<boolean> {
+    return undefined !== (await this.tryfrom(store, name))
+  }
+
+  /** Every named secret at once. Missing ones are an error. */
+  async all(names: Name[]): Promise<Record<string, string>> {
+    const out: Record<string, string> = {}
+
+    for (const name of names) {
+      out[name] = await this.get(name)
+    }
+
+    return out
+  }
+
+  /** A description of each provider, in resolution order. */
+  sources(): string[] {
+    return this.entries.map((entry) => entry.provider.describe())
+  }
+
+  /** The name of each store that can be named by `getfrom`, in resolution
+   * order and without repeats. */
+  stores(): string[] {
+    const out: string[] = []
+
+    for (const entry of this.entries) {
+      if (!out.includes(entry.store)) {
+        out.push(entry.store)
+      }
+    }
+
+    return out
+  }
+
+  /** Replace every value this Sekreto has resolved with `[redacted]`.
+   *
+   * Works whether or not caching is enabled: the redaction list is kept
+   * independently of the read cache. */
+  redact(text: string): string {
+    return redact(text, this.seen)
+  }
+
+  /** Drop cached values, so the next `get` asks the providers again. */
+  refresh(): void {
+    this.cache = []
+  }
+}
+
+/** Make a Sekreto from options. */
+export function sekreto(options?: SekretoOptions): Sekreto {
+  return new Sekreto(options)
+}

package/project/.sdk/tm/ts/src/feature/secrets/sekreto/Sigv4.ts

@@ -0,0 +1,175 @@
+// VENDORED: @voxgig/sekreto 0.1.2 (typescript/src/Sigv4.ts)
+// Source: https://github.com/voxgig/sekreto @ 65009cb5758850db767785ab666e71895f86086b
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// AWS Signature Version 4, hand-rolled.
+//
+// The AWS providers need exactly one thing from the AWS SDK - request
+// signing - and taking the SDK for it would break the no-dependency rule
+// that keeps ten ports honest. SigV4 is a stable, published algorithm
+// built from HMAC-SHA256, which every port's standard library (or, for
+// Rust, a small in-tree implementation) already has.
+//
+// `sigv4` is pure: the caller passes the timestamp, so the same input
+// yields the same signature everywhere. That is what lets the shared spec
+// carry known-answer cases that all ten ports must reproduce bit-for-bit,
+// and lets the integration mock recompute the signature server-side.
+
+// node:crypto is loaded ON FIRST USE, not at import time.
+//
+// Providers.ts imports sigv4 for the AWS providers, and Sekreto.ts imports
+// Providers — so a top-level `node:crypto` here put it in the module graph
+// of every sekreto consumer, including one that never signs anything.
+// Deferring keeps this module pure until an AWS provider actually runs.
+//
+// require(), not `await import()`: these helpers are synchronous and are
+// called from synchronous signing code. The package is CommonJS.
+function crypto(): typeof import('node:crypto') {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require('node:crypto')
+  } catch (err: any) {
+    throw new Error(
+      'sekreto: AWS request signing needs node:crypto, which this runtime ' +
+        'does not provide: ' +
+        err.message,
+      { cause: err },
+    )
+  }
+}
+
+export type Sigv4Input = {
+  method: string
+  /** Full request URL; the host, path and query are signed. */
+  url: string
+  /** Extra headers to sign, e.g. content-type and x-amz-target. */
+  headers?: Record<string, string>
+  body?: string
+  service: string
+  region: string
+  keyid: string
+  secret: string
+  /** STS session token; signed as x-amz-security-token when present. */
+  session?: string
+  /** The signing moment, `YYYYMMDDTHHMMSSZ`. Passed in, never sampled,
+   * so the function stays pure. */
+  datetime: string
+}
+
+/** The headers to attach to the request: authorization, x-amz-date, and
+ * x-amz-security-token when a session token was given. */
+export type Sigv4Output = Record<string, string>
+
+function sha256hex(text: string): string {
+  return crypto().createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+function hmac(key: Buffer | string, text: string): Buffer {
+  return crypto().createHmac('sha256', key).update(text, 'utf8').digest()
+}
+
+/** RFC 3986 escaping, which is stricter than encodeURIComponent: AWS
+ * wants `!`, `'`, `(`, `)` and `*` escaped too. */
+function uriescape(text: string): string {
+  return encodeURIComponent(text).replace(
+    /[!'()*]/g,
+    (ch) => '%' + ch.charCodeAt(0).toString(16).toUpperCase(),
+  )
+}
+
+/** The canonical query string: each pair RFC 3986-escaped, sorted by
+ * escaped key then escaped value. */
+function canonicalquery(query: string): string {
+  if ('' === query) {
+    return ''
+  }
+
+  const pairs = query.split('&').map((pair) => {
+    const eq = pair.indexOf('=')
+    const key = -1 === eq ? pair : pair.slice(0, eq)
+    const value = -1 === eq ? '' : pair.slice(eq + 1)
+    return [uriescape(decodeURIComponent(key)), uriescape(decodeURIComponent(value))]
+  })
+
+  pairs.sort((left, right) => {
+    if (left[0] !== right[0]) {
+      return left[0] < right[0] ? -1 : 1
+    }
+    return left[1] < right[1] ? -1 : left[1] > right[1] ? 1 : 0
+  })
+
+  return pairs.map((pair) => pair[0] + '=' + pair[1]).join('&')
+}
+
+/** Sign one request. Returns the headers to attach. */
+export function sigv4(input: Sigv4Input): Sigv4Output {
+  const url = new URL(input.url)
+
+  const date = input.datetime.slice(0, 8)
+  const body = input.body || ''
+
+  // Every header that will be signed: the caller's extras, plus host and
+  // x-amz-date (and the session token when present), lower-cased and
+  // trimmed the way the canonical form requires.
+  // Canonical header values are trimmed AND internally collapsed -
+  // AWS folds sequential whitespace to one space before signing, so a
+  // header like "a  b" must sign as "a b" or the service refuses it.
+  const headers: Record<string, string> = {}
+  for (const [key, value] of Object.entries(input.headers || {})) {
+    headers[key.toLowerCase()] = String(value).trim().replace(/\s+/g, ' ')
+  }
+  headers['host'] = url.host
+  headers['x-amz-date'] = input.datetime
+  if (input.session) {
+    headers['x-amz-security-token'] = input.session
+  }
+
+  const names = Object.keys(headers).sort()
+  const canonicalheaders = names.map((name) => name + ':' + headers[name] + '\n').join('')
+  const signedheaders = names.join(';')
+
+  const canonicalrequest = [
+    input.method.toUpperCase(),
+    url.pathname || '/',
+    canonicalquery(url.search.replace(/^\?/, '')),
+    canonicalheaders,
+    signedheaders,
+    sha256hex(body),
+  ].join('\n')
+
+  const scope = date + '/' + input.region + '/' + input.service + '/aws4_request'
+
+  const stringtosign = [
+    'AWS4-HMAC-SHA256',
+    input.datetime,
+    scope,
+    sha256hex(canonicalrequest),
+  ].join('\n')
+
+  const kdate = hmac('AWS4' + input.secret, date)
+  const kregion = hmac(kdate, input.region)
+  const kservice = hmac(kregion, input.service)
+  const ksigning = hmac(kservice, 'aws4_request')
+  const signature = crypto()
+    .createHmac('sha256', ksigning)
+    .update(stringtosign, 'utf8')
+    .digest('hex')
+
+  const out: Sigv4Output = {
+    authorization:
+      'AWS4-HMAC-SHA256 Credential=' +
+      input.keyid +
+      '/' +
+      scope +
+      ', SignedHeaders=' +
+      signedheaders +
+      ', Signature=' +
+      signature,
+    'x-amz-date': input.datetime,
+  }
+
+  if (input.session) {
+    out['x-amz-security-token'] = input.session
+  }
+
+  return out
+}

package/project/.sdk/tm/ts/src/feature/secrets/sekreto/index.ts

@@ -0,0 +1,51 @@
+// VENDORED: @voxgig/sekreto 0.1.2 (typescript/src/index.ts)
+// Source: https://github.com/voxgig/sekreto @ 65009cb5758850db767785ab666e71895f86086b
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// @voxgig/sekreto - one interface for secrets, wherever they live.
+
+export {
+  Sekreto,
+  SekretoError,
+  awsparam,
+  envkey,
+  flatname,
+  parsedotenv,
+  redact,
+  sekreto,
+  validname,
+  vaultref,
+} from './Sekreto'
+
+export type { Name, SekretoOptions } from './Sekreto'
+
+// THE CORE SURFACE. Deliberately does NOT re-export the eleven provider
+// kinds that need something of their runtime: pulling one through this
+// file would make all of them reachable and put AWS request signing in
+// every build, which is the thing the split removes.
+//
+// `env` and `memory` are here because they import nothing at all, and a
+// chain with nowhere to read from is not usable or testable.
+//
+// Everything else registers itself when its module is imported:
+//
+//     import '@voxgig/sekreto/provider/dotenv'
+//
+// or, for the old all-in behaviour, `from '@voxgig/sekreto/Providers'`.
+// See docs/design/plugin-providers.md.
+export { envprovider } from './provider/env'
+export { memoryprovider } from './provider/memory'
+
+// A pure validator, no platform dependency - kept on the core surface
+// because callers validate an address before configuring a provider.
+export { checkaddr } from './provider/addr'
+
+export { makeprovider, register, registered, kinds } from './provider/Registry'
+export type { ProviderDefinition } from './provider/Registry'
+
+export type { Provider, ProviderSpec } from './provider/support'
+
+// `sigv4` is NOT on the core surface: it is the node:crypto edge, and
+// only the two aws providers use it. Import it from the module that
+// needs it - `@voxgig/sekreto/provider/aws` - or from the full-set
+// barrel. Re-exporting it here would put request signing in every
+// build again, which is the thing the split removes.