@coffre/core 0.6.2 → 0.7.0

package/dist/recipe.d.ts

@@ -0,0 +1,126 @@
+//#region src/recipe.d.ts
+/**
+ * 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 declare const MIN_BYTES = 1;
+export declare const MAX_BYTES = 256;
+/** Longer than any recipe there is: `bytes:256:base64url` is 19. */
+export declare const MAX_RECIPE_LENGTH = 32;
+export declare const DEFAULT_RECIPE: Recipe;
+export declare const ENCODINGS: {
+  id: Encoding;
+  name: string;
+}[];
+export declare const CURVES: readonly Curve[];
+/** Strongest first, as a new key should be. */
+export declare const PAIRS: {
+  algorithm: PairAlgorithm;
+  curve: Curve;
+}[];
+export declare 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 declare function parseRecipe(text: string): Recipe;
+/** What is wrong with a recipe's text, or null for a recipe. */
+export declare function recipeProblem(text: string): string | null;
+/** A recipe as it is stored and shown: lowercase, every part named. */
+export declare function formatRecipe(recipe: Recipe): string;
+/** A recipe in words, for a confirmation or a listing: "32 random bytes as 64 hex characters". */
+export declare function describeRecipe(recipe: Recipe): string;
+/**
+ * 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 declare function encodedLength(encoding: Encoding, bytes: number): number;
+export type RandomBytes = (bytes: Uint8Array<ArrayBuffer>) => Uint8Array<ArrayBuffer>;
+/** `length` characters of base62, each drawn uniformly by rejecting the bytes 248 to 255. */
+export declare function base62(length: number, random?: RandomBytes): string;
+export declare function randomValue(encoding: Encoding, bytes: number, random?: RandomBytes): string;
+/** A value made by the recipe, with the platform's CSPRNG. */
+export declare function generate(recipe: Recipe): Promise<Generated>;
+/**
+ * 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 declare function generateWrite(key: string, recipe: Recipe, publicKey?: string): Promise<GeneratedWrite>;
+/**
+ * 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 declare function regenerateWrite(key: string, generated: Generation, versionIdOf: (key: string) => string | null): Promise<GeneratedWrite>;
+/**
+ * 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 declare function publicKeyName(privateName: string): string;
+//#endregion

package/dist/recipe.js

@@ -0,0 +1,281 @@
+//#region src/recipe.ts
+const MIN_BYTES = 1;
+const MAX_BYTES = 256;
+/** Longer than any recipe there is: `bytes:256:base64url` is 19. */
+const MAX_RECIPE_LENGTH = 32;
+const DEFAULT_RECIPE = {
+	kind: "random",
+	encoding: "base62",
+	bytes: 32
+};
+const ENCODINGS = [
+	{
+		id: "base62",
+		name: "Letters and digits"
+	},
+	{
+		id: "hex",
+		name: "Hex"
+	},
+	{
+		id: "base64",
+		name: "Base64"
+	},
+	{
+		id: "base64url",
+		name: "Base64 URL"
+	}
+];
+const CURVES = [
+	"P-256",
+	"P-384",
+	"P-521"
+];
+/** Strongest first, as a new key should be. */
+const PAIRS = [
+	{
+		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"
+	}
+];
+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.
+*/
+function parseRecipe(text) {
+	const [kind, size, encoding, ...rest] = text.trim().toLowerCase().split(":");
+	const wrong = (what) => /* @__PURE__ */ new Error(`${what}: a recipe is ${RECIPE_SYNTAX}`);
+	if (text.length > 32) throw wrong(`"${text.slice(0, 32)}…" is too long`);
+	switch (kind) {
+		case "bytes": {
+			if (rest.length > 0) break;
+			const bytes = wholeNumber(size);
+			if (bytes === null || bytes < 1 || bytes > 256) throw wrong(`bytes takes a length from 1 to 256, 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
+			};
+		}
+		case "aes":
+			if (encoding !== void 0) break;
+			if (size !== "128" && size !== "256") throw wrong(`an AES key is 128 or 256 bits, not "${size ?? ""}"`);
+			return {
+				kind: "aes",
+				size: Number(size)
+			};
+		case "ecdsa":
+		case "ecdh": {
+			if (encoding !== void 0) break;
+			const curve = CURVES.find((each) => each.toLowerCase() === size);
+			if (curve === void 0) 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. */
+function recipeProblem(text) {
+	try {
+		parseRecipe(text);
+		return null;
+	} catch (error) {
+		return error.message;
+	}
+}
+/** A recipe as it is stored and shown: lowercase, every part named. */
+function formatRecipe(recipe) {
+	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". */
+function describeRecipe(recipe) {
+	switch (recipe.kind) {
+		case "random": return `${`${recipe.bytes} random ${recipe.bytes === 1 ? "byte" : "bytes"}`} as ${encodedLength(recipe.encoding, recipe.bytes)} ${{
+			base62: "letters and digits",
+			hex: "hex characters",
+			base64: "base64 characters",
+			base64url: "base64 URL 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.
+*/
+function encodedLength(encoding, bytes) {
+	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 = 248;
+const randomBytes = (bytes) => webCrypto().getRandomValues(bytes);
+/** `length` characters of base62, each drawn uniformly by rejecting the bytes 248 to 255. */
+function base62(length, random = randomBytes) {
+	let out = "";
+	while (out.length < length) 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;
+}
+function randomValue(encoding, bytes, random = randomBytes) {
+	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. */
+async function generate(recipe) {
+	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 = 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))
+			};
+		}
+	}
+}
+/**
+* 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.
+*/
+async function generateWrite(key, recipe, publicKey) {
+	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.
+*/
+async function regenerateWrite(key, generated, versionIdOf) {
+	const recipe = parseRecipe(generated.recipe);
+	if (recipe.kind === "pair" && generated.pair === void 0) 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`.
+*/
+function publicKeyName(privateName) {
+	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) {
+	return text !== void 0 && /^\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() {
+	if (globalThis.crypto?.subtle === void 0) throw new Error("This page is not served over HTTPS, so the browser makes no keys here.");
+	return globalThis.crypto.subtle;
+}
+function webCrypto() {
+	if (globalThis.crypto?.getRandomValues === void 0) throw new Error("This runtime has no Web Crypto to draw random bytes from.");
+	return globalThis.crypto;
+}
+function toBase64(bytes) {
+	let binary = "";
+	for (const byte of new Uint8Array(bytes)) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+//#endregion
+export { CURVES, DEFAULT_RECIPE, ENCODINGS, MAX_BYTES, MAX_RECIPE_LENGTH, MIN_BYTES, PAIRS, RECIPE_SYNTAX, base62, describeRecipe, encodedLength, formatRecipe, generate, generateWrite, parseRecipe, publicKeyName, randomValue, recipeProblem, regenerateWrite };

package/dist/{registry-C0NGpxcc.d.ts → registry-Bd7hPoY4.d.ts}

@@ -10,19 +10,31 @@
  * These are immutable UUIDs, never names. Binding to `project/environment/key`
  * names would mean that renaming an environment or a secret key makes every
  * existing ciphertext permanently undecryptable.
+ *
+ * A personal config's values are bound to their owner too, `owner`, which
+ * only the vault's wrap of the data key carries (docs/design/forking.md,
+ * section 4): a forged owner column fails to open, rather than granting.
  */
 type SecretContext = {
   projectId: string;
   environmentId: string;
   secretId: string;
+  /** A personal config's owner, as `ownerKey` hashes them. */
+  owner?: string;
 };
 /**
  * Version prefix for the AAD encoding. If the encoding ever changes, this
  * changes with it, and old ciphertexts keep decrypting under the old rule.
  */
 declare const AAD_VERSION = "coffre.aad.v1";
-/** Throw unless every field is a lowercase UUID. */
+/** Throw unless every field is a lowercase UUID, and an owner a lowercase SHA-256. */
 declare function checkContext(ctx: SecretContext): void;
+/**
+ * A personal config's owner as its values' context binds them: the SHA-256
+ * of the member, `user:ada@acme.example`. Hashed, so it joins the AAD as
+ * unambiguously as a UUID: an email can hold the separator.
+ */
+declare function ownerKey(member: string): string;
 /**
  * Encode a context into AAD bytes.
  *
@@ -123,4 +135,4 @@ declare class KekRegistry {
   unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer>;
 }
 //#endregion
-export { KekProvider as a, WrappedDek as c, checkContext as d, encodeAad as f, KekCancelledError as i, AAD_VERSION as l, DEK_BYTES as n, KekUnavailableError as o, KekBadClaimError as r, KeyOperation as s, KekRegistry as t, SecretContext as u };
+export { KekProvider as a, WrappedDek as c, checkContext as d, encodeAad as f, KekCancelledError as i, AAD_VERSION as l, DEK_BYTES as n, KekUnavailableError as o, ownerKey as p, KekBadClaimError as r, KeyOperation as s, KekRegistry as t, SecretContext as u };

package/dist/schemas.d.ts

@@ -1,6 +1,16 @@
 import { z } from "zod";
 //#region src/schemas.d.ts
 export declare const slug: z.ZodString;
+/**
+ * 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 declare const PERSONAL_SUFFIX = "@me";
+/** `dev@me` as the environment it is a personal config of, `dev`; null for any other slug. */
+export declare function personalOf(environment: string): string | null;
+/** An environment as a path names it: a slug, or `<slug>@me` for your personal config of it. */
+export declare const environmentPath: z.ZodString;
 /** An environment's slug: any slug but the name of one of its project's pages. */
 export declare const environmentSlug: z.ZodString;
 /**

package/dist/schemas.js

@@ -1,8 +1,20 @@
-import { r as INSTANCE_ROLE_NAMES } from "./access-DvwZzqRR.js";
+import { i as INSTANCE_ROLE_NAMES } from "./access-B1wpMzEB.js";
 import { PROJECT_PAGES } from "./pages.js";
 import { z } from "zod";
 //#region src/schemas.ts
 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.
+*/
+const PERSONAL_SUFFIX = "@me";
+/** `dev@me` as the environment it is a personal config of, `dev`; null for any other slug. */
+function personalOf(environment) {
+	return environment.endsWith("@me") ? environment.slice(0, -3) : null;
+}
+/** An environment as a path names it: a slug, or `<slug>@me` for your personal config of it. */
+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. */
 const environmentSlug = slug.refine((value) => !PROJECT_PAGES.includes(value), { error: (issue) => `"${String(issue.input)}" is taken by a project's page, /projects/<project>/${String(issue.input)}: an environment cannot have it` });
 /**
@@ -49,4 +61,4 @@ const scopeInput = z.object({
 const grantId = z.string().uuid();
 const emailAddress = z.string().email().max(320);
 //#endregion
-export { TOMBSTONE, displayName, emailAddress, environmentSlug, folderName, grantId, instanceRole, isTombstone, principalId, principalType, scopeFilter, scopeInput, secretKey, shownMember, slug, tombstoneOf };
+export { PERSONAL_SUFFIX, TOMBSTONE, displayName, emailAddress, environmentPath, environmentSlug, folderName, grantId, instanceRole, isTombstone, personalOf, principalId, principalType, scopeFilter, scopeInput, secretKey, shownMember, slug, tombstoneOf };

package/dist/{types-Mi7-Tzj9.js → types-E1Sz50n6.js}

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 //#region src/context.ts
 /**
 * Version prefix for the AAD encoding. If the encoding ever changes, this
@@ -8,11 +9,21 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 function assertUuid(value, field) {
 	if (typeof value !== "string" || !UUID_RE.test(value)) throw new Error(`context.${field} must be a lowercase UUID, got: ${String(value)}`);
 }
-/** Throw unless every field is a lowercase UUID. */
+/** Throw unless every field is a lowercase UUID, and an owner a lowercase SHA-256. */
 function checkContext(ctx) {
 	assertUuid(ctx.projectId, "projectId");
 	assertUuid(ctx.environmentId, "environmentId");
 	assertUuid(ctx.secretId, "secretId");
+	if (ctx.owner !== void 0 && (typeof ctx.owner !== "string" || !OWNER_RE.test(ctx.owner))) throw new Error(`context.owner must be a lowercase SHA-256, got: ${String(ctx.owner)}`);
+}
+const OWNER_RE = /^[0-9a-f]{64}$/;
+/**
+* A personal config's owner as its values' context binds them: the SHA-256
+* of the member, `user:ada@acme.example`. Hashed, so it joins the AAD as
+* unambiguously as a UUID: an email can hold the separator.
+*/
+function ownerKey(member) {
+	return createHash("sha256").update(member, "utf8").digest("hex");
 }
 /**
 * Encode a context into AAD bytes.
@@ -23,7 +34,7 @@ function checkContext(ctx) {
 */
 function encodeAad(ctx) {
 	checkContext(ctx);
-	return Buffer.from(`${AAD_VERSION}|${ctx.projectId}|${ctx.environmentId}|${ctx.secretId}`, "utf8");
+	return Buffer.from(`${AAD_VERSION}|${ctx.projectId}|${ctx.environmentId}|${ctx.secretId}${ctx.owner === void 0 ? "" : `|owner:${ctx.owner}`}`, "utf8");
 }
 //#endregion
 //#region src/kek/types.ts
@@ -54,4 +65,4 @@ var KekBadClaimError = class extends Error {
 	name = "KekBadClaimError";
 };
 //#endregion
-export { AAD_VERSION as a, KekUnavailableError as i, KekBadClaimError as n, checkContext as o, KekCancelledError as r, encodeAad as s, DEK_BYTES as t };
+export { AAD_VERSION as a, ownerKey as c, KekUnavailableError as i, KekBadClaimError as n, checkContext as o, KekCancelledError as r, encodeAad as s, DEK_BYTES as t };

package/dist/vault.d.ts

@@ -1,4 +1,4 @@
-import { _ as Role, b as ServiceSetting, c as InstanceRole, i as GrantPlace, t as CredentialScope, v as Scope } from "./access-BpcBLDW9.js";
+import { S as ServiceSetting, a as GrantPlace, b as Scope, l as InstanceRole, t as CredentialScope, y as Role } from "./access-CONhKG2P.js";
 //#region src/access-fault.d.ts
 /**
  * Why the vault's members and grants do not follow from its log, as facts
@@ -261,6 +261,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' |
 /**
@@ -358,11 +364,14 @@ 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;
+    through?: string;
   }[];
 };
 /** A reference, as a read names it: its id, and the seq of the vault's `reference.create` entry. */

package/dist/workloads.d.ts

@@ -4,10 +4,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`:
  *
@@ -72,7 +73,12 @@ export declare const MAX_CLAIM_BYTES = 256;
 /** A claim a binding names: one value, or, for what started the run, any of several. */
 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;
@@ -84,9 +90,13 @@ export declare class BindingInvalid extends Error {
 }
 /** The issuer a profile means when none is given: github.com's or gitlab.com's. A GitHub Enterprise Server or a self-managed GitLab names its own. */
 export declare function defaultIssuer(profile: WorkloadProfile): string | null;
+/** The longest issuer a binding with uploaded keys names, in bytes. */
+export declare 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 declare function checkBinding(input: {
   profile: string;
@@ -94,13 +104,29 @@ export declare function checkBinding(input: {
   claims: Record<string, unknown>;
 }, options?: {
   allowLoopback?: boolean;
+  uploaded?: boolean;
 }): BindingPolicy;
 /** A claim's values, one or several. */
 export declare function claimValues(value: ClaimValue | undefined): string[];
+/**
+ * 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 declare function claimAt(claims: Record<string, unknown>, name: string): unknown;
 /**
  * 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