@prestack/thread 0.0.1 → 0.0.3

package/dist/integrations/target.js

@@ -4,23 +4,23 @@ export const REACH = {
     pglite: 'pl_',
     browser: 'zu_',
     https: 'ht_',
-    sdk: 'sdk_',
+    module: 'mod_',
     cli: 'cli_',
 };
 export const HOLDS = {
-    postgres: { takes: 'entities', from: 'server', addressed: true, arrives: null, migrations: true, references: true, sql: true },
-    pglite: { takes: 'entities', from: 'either', addressed: true, arrives: null, migrations: true, references: true, sql: true },
-    browser: { takes: 'entities', from: 'browser', addressed: false, arrives: null, migrations: false, references: false, sql: false },
-    https: { takes: 'calls', from: 'either', addressed: true, arrives: null, migrations: false, references: false, sql: false },
-    sdk: { takes: 'names', from: 'either', addressed: false, arrives: 'npm', migrations: false, references: false, sql: false },
-    cli: { takes: 'names', from: 'server', addressed: false, arrives: 'machine', migrations: false, references: false, sql: false },
+    postgres: { takes: 'entities', from: 'server', addressed: true, arrives: null, migrations: true, references: true, sql: true, driver: 'postgres' },
+    pglite: { takes: 'entities', from: 'either', addressed: true, arrives: null, migrations: true, references: true, sql: true, driver: '@electric-sql/pglite' },
+    browser: { takes: 'entities', from: 'browser', addressed: false, arrives: null, migrations: false, references: false, sql: false, driver: 'zustand' },
+    https: { takes: 'calls', from: 'either', addressed: true, arrives: null, migrations: false, references: false, sql: false, driver: null },
+    module: { takes: 'names', from: 'either', addressed: false, arrives: 'npm', migrations: false, references: false, sql: false, driver: null },
+    cli: { takes: 'names', from: 'server', addressed: false, arrives: 'machine', migrations: false, references: false, sql: false, driver: null },
 };
 export const SAID = {
     postgres: 'A postgres this app connects to over the network. It keeps entities and holds everything a declaration can state about their shape — tables, references and invariants — so what is kept here is held to that shape by the database itself rather than by whatever remembered to check. Who may touch a row is not asked of it: that is answered by the app, against the caller who actually arrived. It is reached from a server only: a connection to it from a page is a database somebody else can open. This is where a thing goes when losing it would matter.',
     pglite: 'A postgres running inside the process that opened it. It keeps entities and holds tables, references and invariants, exactly as the networked one does — what differs is who can reach it, not what it can be told to hold. What belongs here is what the caller is already entitled to see: a local copy, a working set, an offline cache.',
     browser: 'A store in the browser, held in memory the viewer owns. It keeps entities and it is addressed by nothing, because it is already where the code runs. It holds no migration, because a page load builds it from nothing every time. What belongs here is what the interface needs to be responsive and can afford to lose.',
     https: 'Something this app calls over https — a vendor, a service, another app. It accepts calls rather than entities: each is declared with the verb and the path it takes, so a node names the call and never writes a url. Its address and its credential are both secrets, and whether it may be reached from a browser is decided by which kind of secret it needs rather than by the reach itself.',
-    sdk: 'An npm package this app calls directly instead of over the wire — stripe, supabase, neon. Declaring one installs it and reads the methods it publishes, then asks which of them this app may call. What is picked is written down, and a method that is not on that list is refused before the package is imported: what can ever run is fixed when the target is declared, not by whoever calls it. Credentials come from the vault at the moment of the call and are never written anywhere.',
+    module: 'Something this app brings in from outside the repository and calls — an npm package, an SDK, an installer. Declaring one installs it and reads the methods it publishes, then asks which of them this app may call. What is picked is written down, and a method that is not on that list is refused before the package is imported: what can ever run is fixed when the target is declared, not by whoever calls it. A credential is named only if it needs one, and it comes from the vault at the moment of the call and is never written anywhere. A package you only import is a dependency rather than one of these, and the manifest already declares it.',
     cli: 'A program this app runs as a command — git is the one that made this necessary. It is not installed, because it is not a dependency: it is either on the machine or it is not, and declaring one checks that it is there and says what to do when it is not. What it accepts is its subcommands, read off the program itself at the moment it is declared and written down: the whole surface the tool really has, because it was asked rather than typed, and a subcommand that is not on that list never runs. Declaring one is what brings `thread run <name>` into being, so the CLI grows a command by the app stating an integration rather than by anybody writing a verb — and an app that has not declared it has no such command at all.',
 };
 export const CALL_PREFIX = 'cl_';
@@ -33,6 +33,9 @@ export function holdsOf(id) {
     const what = reachOf(id);
     return what === undefined ? undefined : HOLDS[what];
 }
+export function driverOf(id) {
+    return holdsOf(id)?.driver ?? null;
+}
 export function addressOf(one, secrets) {
     if (holdsOf(one.id)?.addressed !== true)
         return undefined;
@@ -71,20 +74,20 @@ export const unreachable = (targets) => targets
     .map((one) => `\`${one.id}\` wears none of the prefixes a target is reached by (${Object.values(REACH).join(', ')}), so ` +
     'nothing can tell how to reach it — and how a thing is reached decides what may be declared for it');
 const SHAPED = {
-    sdk: /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/,
+    module: /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/,
     cli: /^[a-z][a-z0-9-]*$/,
 };
 const EVERY_VALUE = new Set(['constructor', '__proto__', 'prototype']);
 export function misnamed(target, name) {
     const reach = reachOf(target);
-    if (reach !== 'sdk' && reach !== 'cli')
+    if (reach !== 'module' && reach !== 'cli')
         return undefined;
     if (EVERY_VALUE.has(name)) {
         return (`\`${name}\` is a step every JavaScript value has rather than something \`${target}\` offers, and walking to ` +
             'it leaves what was declared');
     }
     if (!SHAPED[reach].test(name)) {
-        return reach === 'sdk'
+        return reach === 'module'
             ? `\`${name}\` is not a method path — one name, or names joined by dots, e.g. \`customers.list\``
             : `\`${name}\` is not a subcommand — one word as the program spells it, e.g. \`commit\` or \`rev-parse\``;
     }

package/dist/integrations/target.ts

@@ -0,0 +1,340 @@
+import type { Member } from '../core/thread.ts'
+
+import { SECRECY, secrecyOf, type Secret } from './secret.ts'
+
+export const REACH = {
+  postgres: 'pg_',
+  pglite: 'pl_',
+  browser: 'zu_',
+  https: 'ht_',
+  module: 'mod_',
+  cli: 'cli_',
+} as const satisfies Readonly<Record<string, string>>
+
+export type Reach = keyof typeof REACH
+
+export interface Holds {
+
+  readonly takes: 'entities' | 'calls' | 'names'
+
+  readonly from: 'server' | 'browser' | 'either'
+
+  readonly addressed: boolean
+
+  readonly arrives: 'npm' | 'machine' | null
+
+  readonly migrations: boolean
+
+  readonly references: boolean
+
+  readonly sql: boolean
+
+  readonly driver: string | null
+}
+
+export const HOLDS: Readonly<Record<Reach, Holds>> = {
+  postgres: { takes: 'entities', from: 'server', addressed: true, arrives: null, migrations: true, references: true, sql: true, driver: 'postgres' },
+  pglite: { takes: 'entities', from: 'either', addressed: true, arrives: null, migrations: true, references: true, sql: true, driver: '@electric-sql/pglite' },
+  browser: { takes: 'entities', from: 'browser', addressed: false, arrives: null, migrations: false, references: false, sql: false, driver: 'zustand' },
+  https: { takes: 'calls', from: 'either', addressed: true, arrives: null, migrations: false, references: false, sql: false, driver: null },
+
+  module: { takes: 'names', from: 'either', addressed: false, arrives: 'npm', migrations: false, references: false, sql: false, driver: null },
+  cli: { takes: 'names', from: 'server', addressed: false, arrives: 'machine', migrations: false, references: false, sql: false, driver: null },
+}
+
+export const SAID: Readonly<Record<Reach, string>> = {
+  postgres:
+    'A postgres this app connects to over the network. It keeps entities and holds everything a declaration can state about their shape — tables, references and invariants — so what is kept here is held to that shape by the database itself rather than by whatever remembered to check. Who may touch a row is not asked of it: that is answered by the app, against the caller who actually arrived. It is reached from a server only: a connection to it from a page is a database somebody else can open. This is where a thing goes when losing it would matter.',
+  pglite:
+    'A postgres running inside the process that opened it. It keeps entities and holds tables, references and invariants, exactly as the networked one does — what differs is who can reach it, not what it can be told to hold. What belongs here is what the caller is already entitled to see: a local copy, a working set, an offline cache.',
+  browser:
+    'A store in the browser, held in memory the viewer owns. It keeps entities and it is addressed by nothing, because it is already where the code runs. It holds no migration, because a page load builds it from nothing every time. What belongs here is what the interface needs to be responsive and can afford to lose.',
+  https:
+    'Something this app calls over https — a vendor, a service, another app. It accepts calls rather than entities: each is declared with the verb and the path it takes, so a node names the call and never writes a url. Its address and its credential are both secrets, and whether it may be reached from a browser is decided by which kind of secret it needs rather than by the reach itself.',
+  module:
+    'Something this app brings in from outside the repository and calls — an npm package, an SDK, an installer. Declaring one installs it and reads the methods it publishes, then asks which of them this app may call. What is picked is written down, and a method that is not on that list is refused before the package is imported: what can ever run is fixed when the target is declared, not by whoever calls it. A credential is named only if it needs one, and it comes from the vault at the moment of the call and is never written anywhere. A package you only import is a dependency rather than one of these, and the manifest already declares it.',
+  cli:
+    'A program this app runs as a command — git is the one that made this necessary. It is not installed, because it is not a dependency: it is either on the machine or it is not, and declaring one checks that it is there and says what to do when it is not. What it accepts is its subcommands, read off the program itself at the moment it is declared and written down: the whole surface the tool really has, because it was asked rather than typed, and a subcommand that is not on that list never runs. Declaring one is what brings `thread run <name>` into being, so the CLI grows a command by the app stating an integration rather than by anybody writing a verb — and an app that has not declared it has no such command at all.',
+}
+
+export interface Target extends Member {
+
+  readonly takes: readonly string[]
+
+  readonly requires: readonly string[]
+
+  readonly uses?: string
+
+  readonly offers?: readonly string[]
+}
+
+export interface Call extends Member {
+
+  readonly of: string
+
+  readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+  readonly path: string
+}
+
+export const CALL_PREFIX = 'cl_'
+
+const FILLED = /\{([a-z][a-z0-9_]*)\}/g
+
+export const fills = (one: Call): readonly string[] => [...one.path.matchAll(FILLED)].map((each) => each[1] ?? '')
+
+export function reachOf(id: string): Reach | undefined {
+  return (Object.keys(REACH) as Reach[]).find((one) => id.startsWith(REACH[one]))
+}
+
+export function holdsOf(id: string): Holds | undefined {
+  const what = reachOf(id)
+  return what === undefined ? undefined : HOLDS[what]
+}
+
+export function driverOf(id: string): string | null {
+  return holdsOf(id)?.driver ?? null
+}
+
+export function addressOf(one: Target, secrets: readonly Secret[]): Secret | undefined {
+
+  if (holdsOf(one.id)?.addressed !== true) return undefined
+  const held = new Map(secrets.map((each) => [each.id, each]))
+  return one.requires.map((each) => held.get(each)).find((each) => each !== undefined && each.sends === undefined)
+}
+
+export function credentialsOf(one: Target, secrets: readonly Secret[]): readonly Secret[] {
+  const held = new Map(secrets.map((each) => [each.id, each]))
+  return one.requires
+    .map((each) => held.get(each))
+    .filter((each): each is Secret => each !== undefined && each.sends !== undefined)
+}
+
+export function servesBrowser(one: Target, secrets: readonly Secret[]): true | string {
+  const holds = holdsOf(one.id)
+  if (holds === undefined) {
+    return `\`${one.id}\` wears none of the prefixes a target is reached by, so nothing can tell where it may be reached from`
+  }
+  if (holds.from === 'server') {
+    return (
+      `\`${one.id}\` is reached over ${String(reachOf(one.id))}, and that reach is server-only whatever it is ` +
+      'authenticated with — the refusal is about the reach itself and not about any credential'
+    )
+  }
+  const held = new Map(secrets.map((each) => [each.id, each]))
+  for (const named of one.requires) {
+    const secret = held.get(named)
+    if (secret === undefined) continue
+    if (secrecyOf(secret.id) === 'server') {
+      return (
+        `\`${one.id}\` requires \`${secret.id}\`, which wears \`${SECRECY.server}\` — a value only a server may hold. ` +
+        'Everything a browser bundle reaches is in the bundle, so this would ship the credential to whoever opens the page'
+      )
+    }
+  }
+  return true
+}
+
+export const unreachable = (targets: readonly Target[]): readonly string[] =>
+  targets
+    .filter((one) => reachOf(one.id) === undefined)
+    .map(
+      (one) =>
+        `\`${one.id}\` wears none of the prefixes a target is reached by (${Object.values(REACH).join(', ')}), so ` +
+        'nothing can tell how to reach it — and how a thing is reached decides what may be declared for it',
+    )
+
+const SHAPED: Readonly<Record<'module' | 'cli', RegExp>> = {
+
+  module: /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/,
+
+  cli: /^[a-z][a-z0-9-]*$/,
+}
+
+const EVERY_VALUE = new Set(['constructor', '__proto__', 'prototype'])
+
+export function misnamed(target: string, name: string): string | undefined {
+  const reach = reachOf(target)
+  if (reach !== 'module' && reach !== 'cli') return undefined
+  if (EVERY_VALUE.has(name)) {
+    return (
+      `\`${name}\` is a step every JavaScript value has rather than something \`${target}\` offers, and walking to ` +
+      'it leaves what was declared'
+    )
+  }
+  if (!SHAPED[reach].test(name)) {
+    return reach === 'module'
+      ? `\`${name}\` is not a method path — one name, or names joined by dots, e.g. \`customers.list\``
+      : `\`${name}\` is not a subcommand — one word as the program spells it, e.g. \`commit\` or \`rev-parse\``
+  }
+  return undefined
+}
+
+export function misaccepted(
+  targets: readonly Target[],
+  entities: readonly string[],
+  calls: readonly Call[],
+): readonly string[] {
+  const isEntity = new Set(entities)
+  const isCall = new Set(calls.map((one) => one.id))
+  const found: string[] = []
+  for (const one of targets) {
+    const holds = holdsOf(one.id)
+    if (holds === undefined) continue
+    for (const named of one.takes) {
+      if (holds.takes === 'entities' && isEntity.has(named)) continue
+      if (holds.takes === 'calls' && isCall.has(named)) continue
+
+      if (holds.takes === 'names') {
+        found.push(
+          `\`${one.id}\` is reached as ${String(reachOf(one.id))} and its \`takes\` names "${named}" — what an ` +
+            'installed package or a program responds to goes in `offers`, not here. `takes` is a demand, and the ' +
+            'descent requires every word on one to be coined by a row in this tree; a method name never can be',
+        )
+        continue
+      }
+      found.push(
+        `\`${one.id}\` is reached over ${String(reachOf(one.id))} and so accepts ${holds.takes}, and its \`takes\` names ` +
+          `"${named}", which is ${isEntity.has(named) ? 'an entity' : isCall.has(named) ? 'a call' : 'nothing this app declares'}`,
+      )
+    }
+  }
+  return found
+}
+
+export function unaddressed(targets: readonly Target[], secrets: readonly Secret[]): readonly string[] {
+  const held = new Map(secrets.map((one) => [one.id, one]))
+  const found: string[] = []
+  for (const one of targets) {
+    const holds = holdsOf(one.id)
+    if (holds === undefined) continue
+    const addresses = one.requires
+      .map((each) => held.get(each))
+      .filter((each): each is Secret => each !== undefined && each.sends === undefined)
+    if (!holds.addressed) {
+
+      if (holds.arrives === null && addresses.length > 0) {
+        found.push(
+          `\`${one.id}\` is reached over ${String(reachOf(one.id))}, which is addressed by nothing and needs nothing to ` +
+            `reach it, and it requires \`${addresses[0]?.id ?? ''}\` — there is nowhere for that value to go`,
+        )
+      }
+      continue
+    }
+    if (addresses.length === 0) {
+      found.push(
+        `\`${one.id}\` is reached over ${String(reachOf(one.id))} and nothing says where it is. Require one secret with ` +
+          'no `sends` — that one is its address. A credential with nowhere to be sent is a value nothing can use',
+      )
+      continue
+    }
+    if (addresses.length > 1) {
+      found.push(
+        `\`${one.id}\` requires ${addresses.map((each) => `\`${each.id}\``).join(' and ')}, and neither says where it goes, ` +
+          'so both read as its address. One place is reached at one address',
+      )
+    }
+  }
+  return found
+}
+
+export function unheld(targets: readonly Target[], secrets: readonly Secret[]): readonly string[] {
+  const known = new Set(secrets.map((one) => one.id))
+  const found: string[] = []
+  for (const one of targets) {
+    for (const named of one.requires) {
+      if (known.has(named)) continue
+      found.push(
+        `\`${one.id}\` requires "${named}", and this app declares no secret by that name. A secret is declared before it ` +
+          'is required, so the one place saying who may hold a value is never whichever place happened to need it',
+      )
+    }
+  }
+  return found
+}
+
+export function unanswered(calls: readonly Call[], targets: readonly Target[]): readonly string[] {
+  const held = new Map(targets.map((one) => [one.id, one]))
+  const found: string[] = []
+  for (const one of calls) {
+    const of = held.get(one.of)
+    if (of === undefined) {
+      found.push(`\`${one.id}\` is a call on "${one.of}", and this app declares no target by that name`)
+      continue
+    }
+    const holds = holdsOf(of.id)
+    if (holds !== undefined && holds.takes !== 'calls') {
+      found.push(
+        `\`${one.id}\` is a call on \`${of.id}\`, which is reached over ${String(reachOf(of.id))} and keeps entities. ` +
+          'A place you keep rows in is not a place you issue verbs at',
+      )
+      continue
+    }
+    if (!of.takes.includes(one.id)) {
+      found.push(
+        `\`${one.id}\` is a call on \`${of.id}\` and \`${of.id}\` does not accept it. Add it to that target's \`takes\` — ` +
+          'what a target accepts is read off the target, not gathered from whatever pointed at it',
+      )
+    }
+  }
+  return found
+}
+
+export function misused(targets: readonly Target[]): readonly string[] {
+  const found: string[] = []
+  for (const one of targets) {
+    const holds = holdsOf(one.id)
+    if (holds === undefined) continue
+    if (holds.arrives !== null && (one.uses ?? '') === '') {
+      found.push(
+        `\`${one.id}\` is reached as ${String(reachOf(one.id))} and does not say what it uses — ` +
+          `${holds.arrives === 'npm' ? 'the npm package to install' : 'the program to run'} goes in \`uses\`, because the ` +
+          'id is what this app calls it and not what it is',
+      )
+      continue
+    }
+    if (holds.arrives === null && one.uses !== undefined) {
+      found.push(
+        `\`${one.id}\` is reached over ${String(reachOf(one.id))}, where nothing is installed and nothing is spawned, ` +
+          `and it states \`uses: '${one.uses}'\` — there is nothing for that name to be`,
+      )
+    }
+  }
+  return found
+}
+
+export function refusals(
+  targets: readonly Target[],
+  secrets: readonly Secret[],
+  calls: readonly Call[],
+  entities: readonly string[],
+): readonly string[] {
+  return [
+    ...unreachable(targets),
+    ...unheld(targets, secrets),
+    ...unaddressed(targets, secrets),
+    ...unanswered(calls, targets),
+    ...misaccepted(targets, entities, calls),
+    ...misused(targets),
+  ]
+}
+
+export function targetOf(entity: string, targets: readonly Target[]): Target | string {
+  const keeping = targets.filter((one) => holdsOf(one.id)?.takes === 'entities')
+  const found = keeping.filter((one) => one.takes.includes(entity))
+  const only = found[0]
+  if (only === undefined) {
+    return (
+      `"${entity}" is kept by no target. Add its id to the \`takes\` of one of ` +
+      `${keeping.length === 0 ? '(this app declares none that keep things)' : keeping.map((one) => `\`${one.id}\``).join(', ')} — ` +
+      'an entity nothing keeps is a table no database builds, and nothing else here would ever say so'
+    )
+  }
+  if (found.length > 1) {
+    return (
+      `"${entity}" is kept by ${found.map((one) => `\`${one.id}\``).join(' and ')}. One thing kept in two places is two ` +
+      'things that will disagree, and neither declaration says which one is right'
+    )
+  }
+  return only
+}

package/dist/integrations/vault.d.ts

@@ -1,5 +1,7 @@
 import type { Env } from '../core/actor.ts';
 export declare const VAULT_DIR = ".thread";
+export declare const SEALED_NAME = "vault.sealed.json";
+export declare const KEY_NAME = "vault.key";
 export declare const SEALED_AT = ".thread/vault.sealed.json";
 export declare const KEY_AT = ".thread/vault.key";
 export declare const ALGORITHM = "aes-256-gcm";

package/dist/integrations/vault.js

@@ -2,8 +2,10 @@ import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 export const VAULT_DIR = '.thread';
-export const SEALED_AT = `${VAULT_DIR}/vault.sealed.json`;
-export const KEY_AT = `${VAULT_DIR}/vault.key`;
+export const SEALED_NAME = 'vault.sealed.json';
+export const KEY_NAME = 'vault.key';
+export const SEALED_AT = `${VAULT_DIR}/${SEALED_NAME}`;
+export const KEY_AT = `${VAULT_DIR}/${KEY_NAME}`;
 export const ALGORITHM = 'aes-256-gcm';
 export const KEY_BYTES = 32;
 const IV_BYTES = 12;

package/dist/integrations/vault.ts

@@ -0,0 +1,136 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import type { Env } from '../core/actor.ts'
+
+export const VAULT_DIR = '.thread'
+
+export const SEALED_NAME = 'vault.sealed.json'
+
+export const KEY_NAME = 'vault.key'
+
+export const SEALED_AT = `${VAULT_DIR}/${SEALED_NAME}`
+
+export const KEY_AT = `${VAULT_DIR}/${KEY_NAME}`
+
+export const ALGORITHM = 'aes-256-gcm'
+
+export const KEY_BYTES = 32
+
+const IV_BYTES = 12
+
+const noKey = (root: string): Error =>
+  new Error(
+    `there is no vault key at ${join(root, KEY_AT)}, so nothing here can open a sealed value. It is deliberately not ` +
+      'in version control — whoever set this app up has it. Ask them for it, or run `thread create secret`, which ' +
+      'generates one when there is none.',
+  )
+
+const unsealable = (named: string, why: string): Error =>
+  new Error(
+    `"${named}" is in the sealed store and would not open: ${why}. Either the key is not the one it was sealed under, ` +
+      'or the store has been edited by hand — it is ciphertext, and there is nothing in it to edit.',
+  )
+
+const undeclared = (named: string, known: readonly string[]): Error =>
+  new Error(
+    `nothing may ask for a secret this app does not declare, and "${named}" is not one of ` +
+      `${known.length === 0 ? '(this app declares none)' : known.join(', ')}. A value is asked for by something that ` +
+      'declared it needed it, or not at all.',
+  )
+
+const unset = (named: string, env: Env): Error =>
+  new Error(
+    `"${named}" is declared and has no value sealed for \`${env}\`. Run \`thread create secret\` and give it one — a ` +
+      'declared secret nothing was ever given is refused here rather than resolved to an empty string.',
+  )
+
+type Store = Record<string, Partial<Record<Env, string>>>
+
+const store = (root: string): Store => {
+  const at = join(root, SEALED_AT)
+  if (!existsSync(at)) return {}
+  try {
+    const held: unknown = JSON.parse(readFileSync(at, 'utf8'))
+    return typeof held === 'object' && held !== null ? (held as Store) : {}
+  } catch {
+    return {}
+  }
+}
+
+export const keyOf = (root: string): Buffer | undefined => {
+  const at = join(root, KEY_AT)
+  if (!existsSync(at)) return undefined
+  try {
+    const held = Buffer.from(readFileSync(at, 'utf8').trim(), 'base64')
+    return held.length === KEY_BYTES ? held : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function keyed(root: string): Buffer {
+  const held = keyOf(root)
+  if (held !== undefined) return held
+  const made = randomBytes(KEY_BYTES)
+  mkdirSync(join(root, VAULT_DIR), { recursive: true })
+  writeFileSync(join(root, KEY_AT), `${made.toString('base64')}\n`, { mode: 0o600 })
+  return made
+}
+
+export function seal(root: string, named: string, env: Env, value: string): void {
+  const key = keyed(root)
+  const iv = randomBytes(IV_BYTES)
+  const cipher = createCipheriv(ALGORITHM, key, iv)
+  const body = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()])
+  const held = store(root)
+  held[named] = { ...held[named], [env]: [iv, cipher.getAuthTag(), body].map((one) => one.toString('base64')).join('.') }
+  const sorted = Object.fromEntries(Object.keys(held).sort().map((one) => [one, held[one]]))
+  const at = join(root, SEALED_AT)
+  mkdirSync(dirname(at), { recursive: true })
+  writeFileSync(at, `${JSON.stringify(sorted, null, 2)}\n`)
+}
+
+export const sealedIn = (root: string, env: Env): readonly string[] =>
+  Object.entries(store(root))
+    .filter(([, held]) => held[env] !== undefined)
+    .map(([named]) => named)
+    .sort()
+
+function unsealed(key: Buffer, named: string, held: string): string {
+  const parts = held.split('.')
+  if (parts.length !== 3) throw unsealable(named, 'it is not three base64 parts separated by dots')
+  const [iv, tag, body] = parts.map((one) => Buffer.from(one, 'base64')) as [Buffer, Buffer, Buffer]
+  try {
+    const decipher = createDecipheriv(ALGORITHM, key, iv)
+    decipher.setAuthTag(tag)
+    return `${decipher.update(body).toString('utf8')}${decipher.final('utf8')}`
+  } catch (thrown) {
+    throw unsealable(named, thrown instanceof Error ? thrown.message : String(thrown))
+  }
+}
+
+export function opened(
+  root: string,
+  declared: readonly string[],
+  env: Env,
+): (refs: readonly string[]) => Promise<Readonly<Record<string, string>>> {
+  const known = new Set(declared)
+  return async (refs) => {
+    if (refs.length === 0) return {}
+    const key = keyOf(root)
+    if (key === undefined) throw noKey(root)
+    const held = store(root)
+    const out: Record<string, string> = {}
+    for (const named of refs) {
+      if (!known.has(named)) throw undeclared(named, [...known].sort())
+      const sealed = held[named]?.[env]
+      if (sealed === undefined) throw unset(named, env)
+      out[named] = unsealed(key, named, sealed)
+    }
+    return out
+  }
+}
+
+export const IGNORES: readonly string[] = [KEY_AT]