@coffre/core 0.6.2 → 0.8.0

package/src/identity/workloads.ts

@@ -3,10 +3,11 @@
  * their platform signs for them (docs/design/oidc.md).
  *
  * A binding names a profile, an issuer, and claims a token must carry, each
- * a top-level string matched exactly. The event that started the run may
- * be any of several: a list. The profile sets the minimum: the server
- * refuses a binding that lacks a claim its profile requires, from the UI,
- * the CLI or the API alike. Say a service is bound to `ci.yml` of
+ * a string matched exactly, at the top of the token or nested in it
+ * (`claimAt`). The event that started the run may be any of several: a
+ * list. The profile sets the minimum: the server refuses a binding that
+ * lacks a claim its profile requires, from the UI, the CLI or the API
+ * alike. Say a service is bound to `ci.yml` of
  * `acme/api`, pushed or dispatched on `main`, or run for a pull request
  * into `main`:
  *
@@ -124,7 +125,12 @@ const ENVIRONMENT = /^(?! )[^\p{Cc}]{1,255}(?<! )$/u;
 export type ClaimValue = string | string[];
 export type BindingClaims = Record<string, ClaimValue>;
 
-/** What makes a binding, checked: its profile, its issuer as a URL, and its claims, sorted. */
+/**
+ * What makes a binding, checked: its profile, its issuer, and its claims,
+ * sorted. The issuer is a URL coffre may fetch, unless the binding carries
+ * its keys (`uploaded`): then coffre fetches nothing, and it is any string,
+ * matched exactly, such as a private Kubernetes cluster's.
+ */
 export type BindingPolicy = { profile: WorkloadProfile; issuer: string; claims: BindingClaims };
 
 /** A binding that breaks a rule, said so an owner can fix it. */
@@ -148,13 +154,18 @@ export function defaultIssuer(profile: WorkloadProfile): string | null {
   return profile === 'custom' ? null : GITHUB_ISSUER;
 }
 
+/** The longest issuer a binding with uploaded keys names, in bytes. */
+export const MAX_ISSUER_BYTES = 400;
+
 /**
  * Check a binding against its profile, and return it as stored: the
- * issuer as given, the claims sorted by name. Throws `BindingInvalid`.
+ * issuer as given, the claims sorted by name. With `uploaded`, the binding
+ * carries its issuer's keys, and its issuer need not be a URL coffre can
+ * fetch. Throws `BindingInvalid`.
  */
 export function checkBinding(
   input: { profile: string; issuer: string | null; claims: Record<string, unknown> },
-  options: { allowLoopback?: boolean } = {},
+  options: { allowLoopback?: boolean; uploaded?: boolean } = {},
 ): BindingPolicy {
   const profile = input.profile as WorkloadProfile;
   if (!WORKLOAD_PROFILES.includes(profile)) {
@@ -162,7 +173,8 @@ export function checkBinding(
   }
   const issuer = input.issuer ?? defaultIssuer(profile);
   if (issuer === null) throw new BindingInvalid('a custom binding names its issuer');
-  checkFetchUrl(issuer, 'the issuer', { allowLoopback: options.allowLoopback, path: true, query: false });
+  if (options.uploaded === true) checkIssuerName(issuer);
+  else checkFetchUrl(issuer, 'the issuer', { allowLoopback: options.allowLoopback, path: true, query: false });
   const forced = forcedProfiles(issuer);
   if (forced !== null && !forced.includes(profile)) {
     throw new BindingInvalid(`${issuer} signs only for the ${forced[0]} profile${forced.length > 1 ? 's' : ''}`);
@@ -204,6 +216,22 @@ export function checkBinding(
   return { profile, issuer, claims };
 }
 
+/**
+ * An issuer whose keys a binding carries: any string a token's `iss` can
+ * be, matched exactly, so none with a control character or a space at
+ * either end. Never github.com's or gitlab.com's, whose keys change when
+ * they rotate them: coffre fetches those.
+ */
+function checkIssuerName(issuer: string): void {
+  if (issuer === '' || /^\s|\s$/.test(issuer) || /\p{Cc}/u.test(issuer)) {
+    throw new BindingInvalid('the issuer is its tokens\' iss, exactly: no control character, no space at either end');
+  }
+  if (new TextEncoder().encode(issuer).length > MAX_ISSUER_BYTES) throw new BindingInvalid(`the issuer is longer than ${MAX_ISSUER_BYTES} bytes`);
+  if (issuer === GITHUB_ISSUER || issuer === GITLAB_ISSUER) {
+    throw new BindingInvalid(`${issuer} publishes its keys and rotates them: coffre fetches them, so upload none`);
+  }
+}
+
 /** A claim's values, one or several. */
 export function claimValues(value: ClaimValue | undefined): string[] {
   return value === undefined ? [] : typeof value === 'string' ? [value] : value;
@@ -258,10 +286,46 @@ function checkGitLab(claims: BindingClaims): void {
   if ((claims.ref as string).startsWith('refs/')) throw new BindingInvalid('GitLab\'s ref is the branch or tag name, without refs/');
 }
 
+/**
+ * A claim of a token, by the name a binding gives it: a top-level claim, or
+ * one nested in objects, its path joined by dots. A key may hold dots of
+ * its own, as Kubernetes' `kubernetes.io` does, so a name is read every way
+ * its dots can split it, and names a claim only when exactly one of those
+ * readings reaches a value; none, or several, and it names nothing. In
+ *
+ *   { "sub": "system:serviceaccount:ci:deploy",
+ *     "kubernetes.io": { "namespace": "ci", "serviceaccount": { "name": "deploy", "uid": "4f1c…" } } }
+ *
+ * `kubernetes.io.serviceaccount.uid` is `4f1c…`, `kubernetes.io` an object,
+ * and `kubernetes.io.pod` nothing.
+ */
+export function claimAt(claims: Record<string, unknown>, name: string): unknown {
+  const parts = name.split('.');
+  let found: unknown;
+  let readings = 0;
+  // Each step takes one key, of one or more parts, from the object it is in; stops once a second reading shows.
+  const walk = (at: unknown, from: number): void => {
+    if (readings > 1) return;
+    if (from === parts.length) {
+      found = at;
+      readings++;
+      return;
+    }
+    if (typeof at !== 'object' || at === null || Array.isArray(at)) return;
+    for (let to = from + 1; to <= parts.length; to++) {
+      const key = parts.slice(from, to).join('.');
+      if (Object.hasOwn(at, key)) walk((at as Record<string, unknown>)[key], to);
+    }
+  };
+  walk(claims, 0);
+  return readings === 1 ? found : undefined;
+}
+
 /**
  * The claims of a verified token that differ from what a binding expects,
  * by name: none when it matches. A claim matches when the token carries its
- * value, or one of its values. On GitHub's profiles, two readings:
+ * value, or one of its values, where `claimAt` reads it. On GitHub's
+ * profiles, two readings:
  *
  * - A `pull_request` run, at `refs/pull/<n>/merge`, counts as a run at the
  *   branch it merges into: its `ref`, and the ref its `workflow_ref` ends
@@ -275,7 +339,7 @@ export function differingClaims(profile: WorkloadProfile, expected: BindingClaim
   const claims = github ? atBaseBranch(token) : token;
   return Object.entries(expected)
     .filter(([name, value]) => {
-      const actual = claims[name];
+      const actual = claimAt(claims, name);
       if (typeof actual !== 'string') return true;
       if (github && name === 'environment') return actual.toLowerCase() !== (value as string).toLowerCase();
       return !claimValues(value).includes(actual);

package/src/kek/aws-kms.ts

@@ -214,7 +214,13 @@ export class AwsKmsKekProvider implements KekProvider {
  */
 function encryptionContext(ctx: SecretContext): Record<string, string> {
   checkContext(ctx);
-  return { 'coffre:project': ctx.projectId, 'coffre:environment': ctx.environmentId, 'coffre:secret': ctx.secretId };
+  return {
+    'coffre:project': ctx.projectId,
+    'coffre:environment': ctx.environmentId,
+    'coffre:secret': ctx.secretId,
+    // A personal config's owner, hashed: KMS refuses to decrypt under any other.
+    ...(ctx.owner === undefined ? {} : { 'coffre:owner': ctx.owner }),
+  };
 }
 
 /**

package/src/recipe.ts

@@ -0,0 +1,309 @@
+/**
+ * How a secret's value is made, when a client makes it rather than a person
+ * typing it: random strings, AES keys and EC key pairs, from Web Crypto
+ * alone, the same in the browser and in the CLI.
+ *
+ * A recipe is short text, `bytes:32:hex`, which the CLI takes as
+ * `--generate` and the server stores beside the version it made, so that
+ * `coffre regenerate` and the page's Regenerate make the next one the same
+ * way. The server checks a recipe's shape and never makes a value: a value
+ * is made where it is sent from, and nothing here talks to the server.
+ *
+ * ```
+ * bytes:<1-256>[:base62|hex|base64|base64url]   random bytes, base62 unless named
+ * aes:<128|256>                                 an AES-GCM key: the raw key, base64
+ * ecdsa:<p-256|p-384|p-521>                     a key pair: PKCS #8 private, SPKI public, base64
+ * ecdh:<p-256|p-384|p-521>
+ * ```
+ */
+
+export type Encoding = 'base62' | 'hex' | 'base64' | 'base64url';
+export type AesSize = 128 | 256;
+export type Curve = 'P-256' | 'P-384' | 'P-521';
+export type PairAlgorithm = 'ECDSA' | 'ECDH';
+
+export type Recipe =
+  | { kind: 'random'; encoding: Encoding; bytes: number }
+  | { kind: 'aes'; size: AesSize }
+  | { kind: 'pair'; algorithm: PairAlgorithm; curve: Curve };
+
+/** A value, and for a key pair its public key, which is saved as a secret of its own. */
+export type Generated = { value: string; publicKey?: string };
+
+/**
+ * What a write says about how its value was made, and what a listing says
+ * of a key's current value: its recipe, and for a key pair the two keys it
+ * wrote together, which only a write of both at once makes.
+ */
+export type Generation = { recipe: string; pair?: KeyPairNames };
+export type KeyPairNames = { private: string; public: string };
+
+export const MIN_BYTES = 1;
+export const MAX_BYTES = 256;
+/** Longer than any recipe there is: `bytes:256:base64url` is 19. */
+export const MAX_RECIPE_LENGTH = 32;
+export const DEFAULT_RECIPE: Recipe = { kind: 'random', encoding: 'base62', bytes: 32 };
+
+export const ENCODINGS: { id: Encoding; name: string }[] = [
+  { id: 'base62', name: 'Letters and digits' },
+  { id: 'hex', name: 'Hex' },
+  { id: 'base64', name: 'Base64' },
+  { id: 'base64url', name: 'Base64 URL' },
+];
+
+export const CURVES: readonly Curve[] = ['P-256', 'P-384', 'P-521'];
+
+/** Strongest first, as a new key should be. */
+export const PAIRS: { algorithm: PairAlgorithm; curve: Curve }[] = [
+  { algorithm: 'ECDSA', curve: 'P-521' },
+  { algorithm: 'ECDSA', curve: 'P-384' },
+  { algorithm: 'ECDSA', curve: 'P-256' },
+  { algorithm: 'ECDH', curve: 'P-521' },
+  { algorithm: 'ECDH', curve: 'P-384' },
+  { algorithm: 'ECDH', curve: 'P-256' },
+];
+
+export const RECIPE_SYNTAX = 'bytes:<1-256>[:base62|hex|base64|base64url], aes:<128|256>, ecdsa:<p-256|p-384|p-521> or ecdh:<curve>';
+
+/**
+ * The recipe a text names, in any case: `bytes:32` is `bytes:32:base62`,
+ * `ECDSA:P-256` is `ecdsa:p-256`. Throws, saying what is wrong, for any
+ * other text.
+ */
+export function parseRecipe(text: string): Recipe {
+  const parts = text.trim().toLowerCase().split(':');
+  const [kind, size, encoding, ...rest] = parts;
+  const wrong = (what: string) => new Error(`${what}: a recipe is ${RECIPE_SYNTAX}`);
+  if (text.length > MAX_RECIPE_LENGTH) throw wrong(`"${text.slice(0, MAX_RECIPE_LENGTH)}…" is too long`);
+  switch (kind) {
+    case 'bytes': {
+      if (rest.length > 0) break;
+      const bytes = wholeNumber(size);
+      if (bytes === null || bytes < MIN_BYTES || bytes > MAX_BYTES) {
+        throw wrong(`bytes takes a length from ${MIN_BYTES} to ${MAX_BYTES}, not "${size ?? ''}"`);
+      }
+      const named = encoding ?? 'base62';
+      if (!ENCODINGS.some((each) => each.id === named)) {
+        throw wrong(`bytes are written as base62, hex, base64 or base64url, not "${named}"`);
+      }
+      return { kind: 'random', bytes, encoding: named as Encoding };
+    }
+    case 'aes': {
+      if (encoding !== undefined) break;
+      if (size !== '128' && size !== '256') throw wrong(`an AES key is 128 or 256 bits, not "${size ?? ''}"`);
+      return { kind: 'aes', size: Number(size) as AesSize };
+    }
+    case 'ecdsa':
+    case 'ecdh': {
+      if (encoding !== undefined) break;
+      const curve = CURVES.find((each) => each.toLowerCase() === size);
+      if (curve === undefined) throw wrong(`${kind} takes the curve p-256, p-384 or p-521, not "${size ?? ''}"`);
+      return { kind: 'pair', algorithm: kind === 'ecdsa' ? 'ECDSA' : 'ECDH', curve };
+    }
+  }
+  throw wrong(`"${text}" is no recipe`);
+}
+
+/** What is wrong with a recipe's text, or null for a recipe. */
+export function recipeProblem(text: string): string | null {
+  try {
+    parseRecipe(text);
+    return null;
+  } catch (error) {
+    return (error as Error).message;
+  }
+}
+
+/** A recipe as it is stored and shown: lowercase, every part named. */
+export function formatRecipe(recipe: Recipe): string {
+  switch (recipe.kind) {
+    case 'random':
+      return `bytes:${recipe.bytes}:${recipe.encoding}`;
+    case 'aes':
+      return `aes:${recipe.size}`;
+    case 'pair':
+      return `${recipe.algorithm.toLowerCase()}:${recipe.curve.toLowerCase()}`;
+  }
+}
+
+/** A recipe in words, for a confirmation or a listing: "32 random bytes as 64 hex characters". */
+export function describeRecipe(recipe: Recipe): string {
+  switch (recipe.kind) {
+    case 'random': {
+      const characters = { base62: 'letters and digits', hex: 'hex characters', base64: 'base64 characters', base64url: 'base64 URL characters' };
+      const bytes = `${recipe.bytes} random ${recipe.bytes === 1 ? 'byte' : 'bytes'}`;
+      return `${bytes} as ${encodedLength(recipe.encoding, recipe.bytes)} ${characters[recipe.encoding]}`;
+    }
+    case 'aes':
+      return `a ${recipe.size}-bit AES-GCM key, raw, base64`;
+    case 'pair':
+      return `an ${recipe.algorithm} ${recipe.curve} key pair: the private key PKCS #8, the public key SPKI, both base64`;
+  }
+}
+
+/**
+ * How many characters carry `bytes` of entropy. Hex and base64 encode the
+ * bytes themselves; base62 draws whole characters, each worth log2(62) bits,
+ * so it takes as many as reach the same number of bits: 43 for 32 bytes.
+ * Base64 pads to a multiple of four; base64 URL leaves the padding off.
+ */
+export function encodedLength(encoding: Encoding, bytes: number): number {
+  switch (encoding) {
+    case 'hex':
+      return bytes * 2;
+    case 'base64':
+      return Math.ceil(bytes / 3) * 4;
+    case 'base64url':
+      return Math.ceil((bytes * 8) / 6);
+    case 'base62':
+      return Math.ceil((bytes * 8) / Math.log2(62));
+  }
+}
+
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+/**
+ * The largest multiple of 62 a byte reaches: 248. A byte below it is taken
+ * modulo 62, and each of the 62 characters has four bytes that make it. The
+ * eight bytes from 248 up are thrown away, as taking them would make the
+ * first eight characters a little likelier than the rest.
+ */
+const BASE62_LIMIT = 256 - (256 % 62);
+
+export type RandomBytes = (bytes: Uint8Array<ArrayBuffer>) => Uint8Array<ArrayBuffer>;
+const randomBytes: RandomBytes = (bytes) => webCrypto().getRandomValues(bytes);
+
+/** `length` characters of base62, each drawn uniformly by rejecting the bytes 248 to 255. */
+export function base62(length: number, random: RandomBytes = randomBytes): string {
+  let out = '';
+  while (out.length < length) {
+    // About 3% of bytes are rejected, so a few spare bytes almost always finish it in one draw.
+    for (const byte of random(new Uint8Array(length - out.length + 8))) {
+      if (byte >= BASE62_LIMIT) continue;
+      out += BASE62[byte % 62];
+      if (out.length === length) break;
+    }
+  }
+  return out;
+}
+
+export function randomValue(encoding: Encoding, bytes: number, random: RandomBytes = randomBytes): string {
+  if (encoding === 'base62') return base62(encodedLength('base62', bytes), random);
+  const drawn = random(new Uint8Array(bytes));
+  if (encoding === 'hex') return [...drawn].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+  const base64 = toBase64(drawn);
+  return encoding === 'base64'
+    ? base64
+    : base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** A value made by the recipe, with the platform's CSPRNG. */
+export async function generate(recipe: Recipe): Promise<Generated> {
+  switch (recipe.kind) {
+    case 'random':
+      return { value: randomValue(recipe.encoding, recipe.bytes) };
+    case 'aes': {
+      const key = await subtle().generateKey({ name: 'AES-GCM', length: recipe.size }, true, [
+        'encrypt',
+        'decrypt',
+      ]);
+      return { value: toBase64(await subtle().exportKey('raw', key)) };
+    }
+    case 'pair': {
+      const usages: KeyUsage[] = recipe.algorithm === 'ECDSA' ? ['sign', 'verify'] : ['deriveBits'];
+      const pair = await subtle().generateKey(
+        { name: recipe.algorithm, namedCurve: recipe.curve },
+        true,
+        usages,
+      );
+      return {
+        value: toBase64(await subtle().exportKey('pkcs8', pair.privateKey)),
+        publicKey: toBase64(await subtle().exportKey('spki', pair.publicKey)),
+      };
+    }
+  }
+}
+
+/**
+ * What a write of generated values sends, by key: each value with how it
+ * was made, and for a regenerate the version it replaces, which the server
+ * holds it to.
+ */
+export type GeneratedWrite = Record<string, { value: string; generated: Generation; replaces?: string }>;
+
+/**
+ * A value made by the recipe for `key`, as a write sends it, and for a key
+ * pair its public key beside it, under `publicKey` or the name that follows
+ * from the private key's (`publicKeyName`). The two halves name each other.
+ */
+export async function generateWrite(key: string, recipe: Recipe, publicKey?: string): Promise<GeneratedWrite> {
+  const text = formatRecipe(recipe);
+  const made = await generate(recipe);
+  if (recipe.kind !== 'pair') return { [key]: { value: made.value, generated: { recipe: text } } };
+  const pair = { private: key, public: publicKey ?? publicKeyName(key) };
+  return {
+    [pair.private]: { value: made.value, generated: { recipe: text, pair } },
+    [pair.public]: { value: made.publicKey!, generated: { recipe: text, pair } },
+  };
+}
+
+/**
+ * The next value of a key by the recipe its current one was made by, as a
+ * listing says it: a key pair's either half makes the pair again, whole,
+ * under the names its halves have now. Each key says the version it
+ * replaces, by the id `versionIdOf` gives as listed, and the server refuses
+ * the write (409) if any has changed since: renamed, archived, typed over
+ * or regenerated meanwhile. A regenerate addresses keys by name, and
+ * without that it could write a name that no longer holds the pair.
+ */
+export async function regenerateWrite(
+  key: string,
+  generated: Generation,
+  versionIdOf: (key: string) => string | null,
+): Promise<GeneratedWrite> {
+  const recipe = parseRecipe(generated.recipe);
+  if (recipe.kind === 'pair' && generated.pair === undefined) {
+    throw new Error(`${key}: ${generated.recipe} makes a key pair, and no pair is named`);
+  }
+  const write = recipe.kind === 'pair' ? await generateWrite(generated.pair!.private, recipe, generated.pair!.public) : await generateWrite(key, recipe);
+  for (const [name, entry] of Object.entries(write)) {
+    const version = versionIdOf(name);
+    if (version === null) throw new Error(`${name} is not listed with a version to regenerate`);
+    entry.replaces = version;
+  }
+  return write;
+}
+
+/**
+ * The name a key pair's public key gets beside its private key's:
+ * `JWT_PRIVATE_KEY` gives `JWT_PUBLIC_KEY`, any other name gains `_PUBLIC`.
+ */
+export function publicKeyName(privateName: string): string {
+  const name = privateName.trim();
+  if (name === '') return '';
+  if (/PRIVATE/.test(name)) return name.replace(/PRIVATE/g, 'PUBLIC');
+  if (/private/.test(name)) return name.replace(/private/g, 'public');
+  return `${name}_PUBLIC`;
+}
+
+function wholeNumber(text: string | undefined): number | null {
+  return text !== undefined && /^\d{1,4}$/.test(text) ? Number(text) : null;
+}
+
+/** Web Crypto's keys need a secure context: HTTPS, or the machine's own address. */
+function subtle(): SubtleCrypto {
+  if (globalThis.crypto?.subtle === undefined) {
+    throw new Error('This page is not served over HTTPS, so the browser makes no keys here.');
+  }
+  return globalThis.crypto.subtle;
+}
+
+function webCrypto(): Crypto {
+  if (globalThis.crypto?.getRandomValues === undefined) throw new Error('This runtime has no Web Crypto to draw random bytes from.');
+  return globalThis.crypto;
+}
+
+function toBase64(bytes: ArrayBuffer | Uint8Array): string {
+  let binary = '';
+  for (const byte of new Uint8Array(bytes)) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}

package/src/schemas.ts

@@ -4,6 +4,21 @@ import { INSTANCE_ROLE_NAMES, type InstanceRole } from './access.ts';
 import { PROJECT_PAGES } from './pages.ts';
 
 export const slug = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
+/**
+ * Your personal config of an environment, in a path: `market/dev@me`
+ * (docs/design/forking.md). A read falls back to `market/dev` when you have
+ * none; a write never does.
+ */
+export const PERSONAL_SUFFIX = '@me';
+
+/** `dev@me` as the environment it is a personal config of, `dev`; null for any other slug. */
+export function personalOf(environment: string): string | null {
+  return environment.endsWith(PERSONAL_SUFFIX) ? environment.slice(0, -PERSONAL_SUFFIX.length) : null;
+}
+
+/** An environment as a path names it: a slug, or `<slug>@me` for your personal config of it. */
+export const environmentPath = z.string().refine((value) => slug.safeParse(personalOf(value) ?? value).success, 'not a valid environment');
+
 /** An environment's slug: any slug but the name of one of its project's pages. */
 export const environmentSlug = slug.refine((value) => !(PROJECT_PAGES as readonly string[]).includes(value), {
   error: (issue) => `"${String(issue.input)}" is taken by a project's page, /projects/<project>/${String(issue.input)}: an environment cannot have it`,

package/src/vault.ts

@@ -163,6 +163,12 @@ export type RefusalCode =
   | 'bulk_limit'
   /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
   | 'bad_claim'
+  /**
+   * A person asked for values to be handed back, where people get stand-ins
+   * (`people: 'stand-ins'`): their apps use values through the credential
+   * proxy instead, and only service accounts read them.
+   */
+  | 'stand_ins'
   /**
    * The project or environment was deleted for good: nothing under it is
    * opened or wrapped again, whatever grant would cover it.
@@ -170,6 +176,12 @@ export type RefusalCode =
   | 'deleted'
   /** The reference read through was ended: broken, or replaced by a value. */
   | 'ended'
+  /**
+   * A personal config's value, which only its owner opens or writes, and
+   * only while they read the environment it is a config of: no grant or
+   * role reaches it, an Owner's included. Nor does any reference.
+   */
+  | 'personal'
   /** Not allowed to manage access, members or the log. */
   | 'not_allowed'
   /**
@@ -222,8 +234,21 @@ export type WrappedKey = { kekProvider: string; kekId: string; kekVersion: strin
  */
 export type KeyChecks = { current: { kekProvider: string; kekId: string }; checks: (WrappedKey & { seq: number })[] };
 
-/** Why someone reads: shown in the log, and the same rules apply to each. A fork reads to `copy`. */
-export type Purpose = 'reveal' | 'run' | 'compare' | 'copy';
+/**
+ * Why someone reads: shown in the log, and the same rules apply to each. A
+ * fork reads to `copy`. The credential proxy reads to `use`, a value it
+ * injects into a request and never hands back, or to `expose`, one the
+ * deployment lets people's apps hold. Where people get stand-ins
+ * (`people: 'stand-ins'`), a person opens nothing to `reveal`, `run` or
+ * `compare` (`HANDED_BACK`).
+ */
+export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
+
+/**
+ * What a person never opens where people get stand-ins: values handed back
+ * to them, and a dry run's `compare`, which tells them whether a guess was right.
+ */
+export const HANDED_BACK: readonly Purpose[] = ['reveal', 'run', 'compare'];
 
 /** Ties the vault's entries to the app's request and audit rows. */
 type Correlation = {
@@ -255,9 +280,11 @@ export type UnwrapInput = Correlation & Through & {
   /**
    * `via` reads a source's current version through a reference: the vault
    * checks the reader's grants on the holder's environment, as its
-   * `reference.create` entry names it, not on the source's.
+   * `reference.create` entry names it, not on the source's. `through`, an
+   * environment's id, is the fork an inherited value is read in: the vault
+   * logs the read there too, and decides on the value's own environment.
    */
-  items: { secretVersionId: string; via?: Via }[];
+  items: { secretVersionId: string; via?: Via; through?: string }[];
 };
 
 /** A reference, as a read names it: its id, and the seq of the vault's `reference.create` entry. */