@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/team-secrets/keys.js

@@ -0,0 +1,158 @@
+/**
+ * Machine keys for team secrets (team-secrets spec §2, §4): one X25519 pair to decrypt and one Ed25519
+ * pair to sign, per machine per workspace. Keys travel as base64url of their raw 32 bytes, which is what
+ * a JWK's `x` and `d` already are, so `node:crypto` imports them without any DER handling.
+ *
+ * Pure: no I/O. The desktop keeps the private halves in its keychain-backed store; nothing else does.
+ */
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync } from 'node:crypto';
+import { teamSecretsError } from './errors.js';
+/** A key id: the first 26 base32 characters of SHA-256 over both public keys. */
+export const KEY_ID_PATTERN = /^[A-Z2-7]{26}$/;
+export function base64url(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/;
+/**
+ * Strict base64url decoding: Node's own decoder tolerates padding, standard `+`/`/`, and embedded
+ * whitespace, silently turning any of those into *some* bytes. A team-secrets field is either exactly
+ * base64url or it is corrupt, so this instead requires the alphabet `[A-Za-z0-9_-]` with no padding, and
+ * that re-encoding the decoded bytes reproduces the input exactly (catching a truncated last group, which
+ * the pattern alone would not).
+ *
+ * @throws WirebenchError `team-secrets-bad-key` if `text` is not strictly base64url.
+ */
+export function fromBase64url(text) {
+    if (!BASE64URL_PATTERN.test(text)) {
+        throw teamSecretsError('team-secrets-bad-key');
+    }
+    const bytes = Buffer.from(text, 'base64url');
+    if (base64url(bytes) !== text) {
+        throw teamSecretsError('team-secrets-bad-key');
+    }
+    return bytes;
+}
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+/** RFC 4648 base32 without padding. */
+export function base32(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of bytes) {
+        // Only the bits not yet written are kept (fewer than 13), so the number never overflows.
+        value = ((value << 8) | byte) & 0x1fff;
+        bits += 8;
+        while (bits >= 5) {
+            out += BASE32_ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        out += BASE32_ALPHABET[(value << (5 - bits)) & 31];
+    }
+    return out;
+}
+const PUBLIC_KEY_LENGTH = 32;
+/** @throws WirebenchError `team-secrets-bad-key` unless `bytes` is exactly `length` long. */
+function assertKeyLength(bytes, length) {
+    if (bytes.length !== length) {
+        throw teamSecretsError('team-secrets-bad-key');
+    }
+    return bytes;
+}
+function publicDigest(keys) {
+    return createHash('sha256')
+        .update(assertKeyLength(fromBase64url(keys.encryptionKey), PUBLIC_KEY_LENGTH))
+        .update(assertKeyLength(fromBase64url(keys.signingKey), PUBLIC_KEY_LENGTH))
+        .digest();
+}
+export function keyIdOf(keys) {
+    return base32(publicDigest(keys)).slice(0, 26);
+}
+/** What an admin reads out to the person (§3.2): the first 16 hex of the same digest, in groups of four. */
+export function fingerprintOf(keys) {
+    return publicDigest(keys).toString('hex').slice(0, 16).match(/.{4}/g)?.join(' ') ?? '';
+}
+export function generateMachineKeys() {
+    const encryption = generateKeyPairSync('x25519').privateKey.export({ format: 'jwk' });
+    const signing = generateKeyPairSync('ed25519').privateKey.export({ format: 'jwk' });
+    const publicKeys = { encryptionKey: String(encryption.x), signingKey: String(signing.x) };
+    return {
+        ...publicKeys,
+        keyId: keyIdOf(publicKeys),
+        encryptionPrivate: String(encryption.d),
+        signingPrivate: String(signing.d),
+    };
+}
+export function encryptionPublicKey(raw) {
+    assertKeyLength(fromBase64url(raw), PUBLIC_KEY_LENGTH);
+    return createPublicKey({ key: { kty: 'OKP', crv: 'X25519', x: raw }, format: 'jwk' });
+}
+export function encryptionPrivateKey(keys) {
+    return createPrivateKey({
+        key: { kty: 'OKP', crv: 'X25519', x: keys.encryptionKey, d: keys.encryptionPrivate },
+        format: 'jwk',
+    });
+}
+export function signingPublicKey(raw) {
+    assertKeyLength(fromBase64url(raw), PUBLIC_KEY_LENGTH);
+    return createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: raw }, format: 'jwk' });
+}
+export function signingPrivateKey(keys) {
+    return createPrivateKey({
+        key: { kty: 'OKP', crv: 'Ed25519', x: keys.signingKey, d: keys.signingPrivate },
+        format: 'jwk',
+    });
+}
+/** The stored form, kept in the keychain-backed store only. */
+export function serializeMachineKeys(keys) {
+    return JSON.stringify({
+        keyId: keys.keyId,
+        encryptionKey: keys.encryptionKey,
+        encryptionPrivate: keys.encryptionPrivate,
+        signingKey: keys.signingKey,
+        signingPrivate: keys.signingPrivate,
+    });
+}
+/** The public half (base64url `x`) a JWK private key exports, i.e. what its private half actually is a key for. */
+function publicHalfOf(privateKey) {
+    return String(createPublicKey(privateKey).export({ format: 'jwk' }).x);
+}
+/**
+ * Reads the stored form back; `undefined` for anything malformed, whose key id does not match its public
+ * keys, or whose public keys are not the ones its private halves actually derive (a stored file could
+ * otherwise carry a public key from one machine paired with a private key from another).
+ */
+export function parseMachineKeys(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return undefined;
+    }
+    const fields = parsed;
+    const names = ['keyId', 'encryptionKey', 'encryptionPrivate', 'signingKey', 'signingPrivate'];
+    if (names.some((name) => typeof fields[name] !== 'string')) {
+        return undefined;
+    }
+    const keys = Object.fromEntries(names.map((name) => [name, fields[name]]));
+    try {
+        if (keyIdOf(keys) !== keys.keyId) {
+            return undefined;
+        }
+        if (publicHalfOf(encryptionPrivateKey(keys)) !== keys.encryptionKey) {
+            return undefined;
+        }
+        if (publicHalfOf(signingPrivateKey(keys)) !== keys.signingKey) {
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return keys;
+}

package/dist/team-secrets/log.d.ts

@@ -0,0 +1,48 @@
+import type { AccessEntryFile, KeyRequestFile } from './schema.js';
+/** A key request that proved possession of its keys. */
+export interface KeyInfo {
+    readonly keyId: string;
+    readonly encryptionKey: string;
+    readonly signingKey: string;
+    readonly name: string;
+    readonly email: string;
+    readonly machine: string;
+    readonly requestedAt: string;
+    readonly fingerprint: string;
+}
+export interface Removal {
+    readonly keyId: string;
+    readonly at: string;
+    readonly by: string;
+    readonly entryId: string;
+}
+export type LogProblem = 'unknown-signer' | 'bad-signature' | 'second-genesis' | 'no-genesis' | 'not-allowed' | 'unknown-key' | 'already-approved' | 'removed-key' | 'not-approved' | 'not-admin' | 'already-admin' | 'last-admin' | 'last-approved' | 'wrong-authority';
+export interface AccessState {
+    /** A valid genesis was replayed. */
+    readonly on: boolean;
+    readonly authority?: 'signed' | 'server';
+    readonly genesisId?: string;
+    readonly keys: ReadonlyMap<string, KeyInfo>;
+    readonly approved: ReadonlySet<string>;
+    /** Always empty with `authority: server`. */
+    readonly admins: ReadonlySet<string>;
+    readonly removed: readonly Removal[];
+    readonly problems: readonly {
+        readonly id: string;
+        readonly problem: LogProblem;
+    }[];
+}
+/** The key requests whose id matches their keys and whose self-signature verifies, by key id. */
+export declare function verifiedKeys(files: readonly KeyRequestFile[]): Map<string, KeyInfo>;
+/**
+ * The id for a new access entry: a ULID for `now`, or just after the newest existing one when this
+ * machine's clock is behind it, so the entry always replays after what its writer saw (§15 clock skew).
+ */
+export declare function nextAccessEntryId(existing: readonly string[], now: number): string;
+/**
+ * Replays `entries` in ULID order. `genesisId`, when given, is the only entry allowed to be the genesis
+ * (plan decision 4); without it the first valid genesis wins.
+ */
+export declare function replayAccessLog(keys: ReadonlyMap<string, KeyInfo>, entries: readonly AccessEntryFile[], options?: {
+    readonly genesisId?: string;
+}): AccessState;

package/dist/team-secrets/log.js

@@ -0,0 +1,175 @@
+/**
+ * The access log (§2, §3.7): `access/<ulid>.yaml` entries replayed in ULID order give the approved keys
+ * and the admins. With `authority: signed` (git and folder shares) an entry counts only when an admin at
+ * that point of the replay signed it; with `authority: server` any approved key's signature counts, and
+ * the server refuses a non-admin's push to `access/` (§5.1). Invalid entries are skipped and listed.
+ */
+import { decodeTime, ulid } from 'ulidx';
+import { fingerprintOf, keyIdOf } from './keys.js';
+import { verifyDocument } from './sign.js';
+/** The key requests whose id matches their keys and whose self-signature verifies, by key id. */
+export function verifiedKeys(files) {
+    const keys = new Map();
+    for (const file of files) {
+        if (keyIdOf(file) !== file.keyId || !verifyDocument(file, file.signingKey)) {
+            continue;
+        }
+        keys.set(file.keyId, {
+            keyId: file.keyId,
+            encryptionKey: file.encryptionKey,
+            signingKey: file.signingKey,
+            name: file.name,
+            email: file.email,
+            machine: file.machine,
+            requestedAt: file.requestedAt,
+            fingerprint: fingerprintOf(file),
+        });
+    }
+    return keys;
+}
+/**
+ * The id for a new access entry: a ULID for `now`, or just after the newest existing one when this
+ * machine's clock is behind it, so the entry always replays after what its writer saw (§15 clock skew).
+ */
+export function nextAccessEntryId(existing, now) {
+    const last = existing.reduce((max, id) => (max === undefined || id > max ? id : max), undefined);
+    if (last === undefined) {
+        return ulid(now);
+    }
+    // A corrupted or out-of-range id (outside what `ULID_PATTERN` accepts) must never crash entry
+    // creation — decodeTime throws on those, so fall back to `now` rather than propagate.
+    let lastTime;
+    try {
+        lastTime = decodeTime(last);
+    }
+    catch {
+        return ulid(now);
+    }
+    return ulid(Math.max(now, lastTime + 1));
+}
+/**
+ * Replays `entries` in ULID order. `genesisId`, when given, is the only entry allowed to be the genesis
+ * (plan decision 4); without it the first valid genesis wins.
+ */
+export function replayAccessLog(keys, entries, options = {}) {
+    const sorted = [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    let authority;
+    let genesisId;
+    const approved = new Set();
+    const admins = new Set();
+    const removedKeys = new Set();
+    const removed = [];
+    const problems = [];
+    for (const entry of sorted) {
+        const reject = (problem) => {
+            problems.push({ id: entry.id, problem });
+        };
+        const signer = keys.get(entry.by);
+        if (signer === undefined) {
+            reject('unknown-signer');
+            continue;
+        }
+        if (!verifyDocument(entry, signer.signingKey)) {
+            reject('bad-signature');
+            continue;
+        }
+        if (entry.action === 'genesis') {
+            if (authority !== undefined || (options.genesisId !== undefined && options.genesisId !== entry.id)) {
+                reject('second-genesis');
+                continue;
+            }
+            if (entry.key !== entry.by || entry.authority === undefined) {
+                reject('not-allowed');
+                continue;
+            }
+            authority = entry.authority;
+            genesisId = entry.id;
+            approved.add(entry.key);
+            if (authority === 'signed') {
+                admins.add(entry.key);
+            }
+            continue;
+        }
+        if (authority === undefined) {
+            reject('no-genesis');
+            continue;
+        }
+        const mayManage = authority === 'signed' ? admins.has(entry.by) : approved.has(entry.by);
+        if (!mayManage) {
+            reject('not-allowed');
+            continue;
+        }
+        if (!keys.has(entry.key)) {
+            reject('unknown-key');
+            continue;
+        }
+        switch (entry.action) {
+            case 'approve':
+                if (removedKeys.has(entry.key)) {
+                    reject('removed-key');
+                }
+                else if (approved.has(entry.key)) {
+                    reject('already-approved');
+                }
+                else {
+                    approved.add(entry.key);
+                }
+                break;
+            case 'remove':
+                if (!approved.has(entry.key)) {
+                    reject('not-approved');
+                }
+                else if (authority === 'signed' && admins.has(entry.key) && admins.size === 1) {
+                    reject('last-admin');
+                }
+                else if (authority === 'server' && approved.size === 1) {
+                    reject('last-approved');
+                }
+                else {
+                    approved.delete(entry.key);
+                    admins.delete(entry.key);
+                    removedKeys.add(entry.key);
+                    removed.push({ keyId: entry.key, at: entry.at, by: entry.by, entryId: entry.id });
+                }
+                break;
+            case 'grant-admin':
+                if (authority !== 'signed') {
+                    reject('wrong-authority');
+                }
+                else if (!approved.has(entry.key)) {
+                    reject('not-approved');
+                }
+                else if (admins.has(entry.key)) {
+                    reject('already-admin');
+                }
+                else {
+                    admins.add(entry.key);
+                }
+                break;
+            case 'revoke-admin':
+                if (authority !== 'signed') {
+                    reject('wrong-authority');
+                }
+                else if (!admins.has(entry.key)) {
+                    reject('not-admin');
+                }
+                else if (admins.size === 1) {
+                    reject('last-admin');
+                }
+                else {
+                    admins.delete(entry.key);
+                }
+                break;
+        }
+    }
+    return {
+        on: authority !== undefined,
+        ...(authority !== undefined ? { authority } : {}),
+        ...(genesisId !== undefined ? { genesisId } : {}),
+        keys,
+        approved,
+        admins,
+        removed,
+        problems,
+    };
+}

package/dist/team-secrets/resolve-conflict.d.ts

@@ -0,0 +1,7 @@
+/**
+ * §3.5: a vault entry is a whole-file value. Of two concurrent versions the later `updatedAt` wins, then
+ * the lower `updatedBy`; a side without the file (deleted, or unreadable) loses to one that has it (plan
+ * decision 8). Both missing: theirs.
+ */
+import type { VaultEntryFile } from './schema.js';
+export declare function vaultConflictWinner(mine: VaultEntryFile | undefined, theirs: VaultEntryFile | undefined): 'mine' | 'theirs';

package/dist/team-secrets/resolve-conflict.js

@@ -0,0 +1,14 @@
+export function vaultConflictWinner(mine, theirs) {
+    if (mine === undefined) {
+        return 'theirs';
+    }
+    if (theirs === undefined) {
+        return 'mine';
+    }
+    const mineAt = Date.parse(mine.updatedAt);
+    const theirsAt = Date.parse(theirs.updatedAt);
+    if (mineAt !== theirsAt) {
+        return mineAt > theirsAt ? 'mine' : 'theirs';
+    }
+    return mine.updatedBy < theirs.updatedBy ? 'mine' : 'theirs';
+}

package/dist/team-secrets/schema.d.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+export declare const TEAM_SECRETS_FORMAT_VERSION = 1;
+/**
+ * A Crockford-base32 ULID, as `ulidx` writes it. The first character is restricted to `0`-`7`: a ULID's
+ * 48-bit timestamp fills at most that much of the first base32 group, so a wider first character (a
+ * corrupted or adversarial id) would decode to a timestamp `ulidx`'s `decodeTime` rejects outright — this
+ * pattern keeps that failure at parse time instead of wherever `decodeTime` is next called.
+ */
+export declare const ULID_PATTERN: RegExp;
+export declare const keyIdSchema: z.ZodString;
+export declare const keyRequestFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    keyId: z.ZodString;
+    encryptionKey: z.ZodString;
+    signingKey: z.ZodString;
+    name: z.ZodString;
+    email: z.ZodString;
+    machine: z.ZodString;
+    requestedAt: z.ZodISODateTime;
+    signature: z.ZodString;
+}, z.core.$strict>;
+export type KeyRequestFile = z.infer<typeof keyRequestFileSchema>;
+export declare const ACCESS_ACTIONS: readonly ["genesis", "approve", "remove", "grant-admin", "revoke-admin"];
+export type AccessAction = (typeof ACCESS_ACTIONS)[number];
+/** `authority` is the genesis entry's own field: present exactly when `action === 'genesis'`. */
+export declare const accessEntryFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    id: z.ZodString;
+    action: z.ZodEnum<{
+        remove: "remove";
+        genesis: "genesis";
+        approve: "approve";
+        "grant-admin": "grant-admin";
+        "revoke-admin": "revoke-admin";
+    }>;
+    authority: z.ZodOptional<z.ZodEnum<{
+        server: "server";
+        signed: "signed";
+    }>>;
+    key: z.ZodString;
+    by: z.ZodString;
+    at: z.ZodISODateTime;
+    signature: z.ZodString;
+}, z.core.$strict>;
+export type AccessEntryFile = z.infer<typeof accessEntryFileSchema>;
+/** Which secret an entry holds: a keychain ref as the tree names it, or a `${secret:name}` token of one project. */
+export declare const secretKeySchema: z.ZodUnion<readonly [z.ZodObject<{
+    ref: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    token: z.ZodObject<{
+        projectId: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>]>;
+export type SecretKey = z.infer<typeof secretKeySchema>;
+export declare const vaultEntryFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    secret: z.ZodUnion<readonly [z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        token: z.ZodObject<{
+            projectId: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>;
+    label: z.ZodString;
+    cipher: z.ZodString;
+    wraps: z.ZodRecord<z.ZodString, z.ZodString>;
+    updatedAt: z.ZodISODateTime;
+    updatedBy: z.ZodString;
+    signature: z.ZodString;
+}, z.core.$strict>;
+export type VaultEntryFile = z.infer<typeof vaultEntryFileSchema>;
+export declare const TEAM_SECRETS_KEYS_DIR = "team-secrets/keys";
+export declare const TEAM_SECRETS_ACCESS_DIR = "team-secrets/access";
+export declare const TEAM_SECRETS_VALUES_DIR = "team-secrets/values";
+export declare function keyRequestPath(keyId: string): string;
+export declare function accessEntryPath(id: string): string;
+export declare function vaultEntryPath(id: string): string;
+export declare function isTeamSecretsPath(path: string): boolean;
+export declare function isVaultEntryPath(path: string): boolean;
+export declare function vaultEntryIdOfPath(path: string): string | undefined;
+/** Plan decision 3: base32 of SHA-256 over `ref:<ref>` or `token:<projectId>\n<name>`, first 26 characters. */
+export declare function vaultEntryId(secret: SecretKey): string;
+export declare function sameSecret(a: SecretKey, b: SecretKey): boolean;
+export declare function teamSecretsFileText(doc: object): string;
+export declare function parseTeamSecretsFile<S extends z.ZodType>(schema: S, text: string): z.infer<S> | undefined;
+/** Everything under `team-secrets/`, parsed. `values` is keyed by the file's id. */
+export interface TeamSecretsFiles {
+    readonly keys: KeyRequestFile[];
+    readonly access: AccessEntryFile[];
+    readonly values: Map<string, VaultEntryFile>;
+    /** Tree paths that are malformed, or whose name is not their id. */
+    readonly invalid: string[];
+}
+/** Parses the tree's team-secrets files, given as tree path → text. Other paths are ignored. */
+export declare function readTeamSecretsFiles(files: ReadonlyMap<string, string>): TeamSecretsFiles;

package/dist/team-secrets/schema.js

@@ -0,0 +1,157 @@
+/**
+ * The three kinds of file under `team-secrets/` (§4): key requests, access-log entries and vault entries,
+ * one YAML document each, written by the engine's serializer. Binary fields are base64url without padding.
+ * Parsing never throws: a malformed or misnamed file is listed in `invalid` and otherwise ignored.
+ */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { parseYaml, stringifyYaml } from '../project/yaml.js';
+import { SECRET_NAME_PATTERN } from '../secrets/secret-token.js';
+import { TEAM_SECRETS_DIR } from '../workspace/paths.js';
+import { base32, KEY_ID_PATTERN } from './keys.js';
+export const TEAM_SECRETS_FORMAT_VERSION = 1;
+/**
+ * A Crockford-base32 ULID, as `ulidx` writes it. The first character is restricted to `0`-`7`: a ULID's
+ * 48-bit timestamp fills at most that much of the first base32 group, so a wider first character (a
+ * corrupted or adversarial id) would decode to a timestamp `ulidx`'s `decodeTime` rejects outright — this
+ * pattern keeps that failure at parse time instead of wherever `decodeTime` is next called.
+ */
+export const ULID_PATTERN = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const base64urlSchema = z.string().regex(/^[A-Za-z0-9_-]+$/);
+/** 32 bytes as base64url without padding. */
+const publicKeySchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
+/** An Ed25519 signature: 64 bytes as base64url without padding, always exactly 86 characters. */
+const signatureSchema = z.string().regex(/^[A-Za-z0-9_-]{86}$/);
+const isoSchema = z.iso.datetime({ offset: true });
+export const keyIdSchema = z.string().regex(KEY_ID_PATTERN);
+export const keyRequestFileSchema = z.strictObject({
+    version: z.literal(TEAM_SECRETS_FORMAT_VERSION),
+    keyId: keyIdSchema,
+    encryptionKey: publicKeySchema,
+    signingKey: publicKeySchema,
+    name: z.string().min(1).max(200),
+    email: z.string().max(320),
+    machine: z.string().min(1).max(200),
+    requestedAt: isoSchema,
+    signature: signatureSchema,
+});
+export const ACCESS_ACTIONS = ['genesis', 'approve', 'remove', 'grant-admin', 'revoke-admin'];
+/** `authority` is the genesis entry's own field: present exactly when `action === 'genesis'`. */
+export const accessEntryFileSchema = z
+    .strictObject({
+    version: z.literal(TEAM_SECRETS_FORMAT_VERSION),
+    id: z.string().regex(ULID_PATTERN),
+    action: z.enum(ACCESS_ACTIONS),
+    authority: z.enum(['signed', 'server']).optional(),
+    key: keyIdSchema,
+    by: keyIdSchema,
+    at: isoSchema,
+    signature: signatureSchema,
+})
+    .refine((entry) => (entry.action === 'genesis') === (entry.authority !== undefined), {
+    message: 'authority is required on a genesis entry and forbidden on any other action',
+});
+/** Which secret an entry holds: a keychain ref as the tree names it, or a `${secret:name}` token of one project. */
+export const secretKeySchema = z.union([
+    z.strictObject({ ref: z.string().min(1).max(200) }),
+    z.strictObject({
+        token: z.strictObject({ projectId: z.string().min(1).max(200), name: z.string().regex(SECRET_NAME_PATTERN) }),
+    }),
+]);
+export const vaultEntryFileSchema = z.strictObject({
+    version: z.literal(TEAM_SECRETS_FORMAT_VERSION),
+    secret: secretKeySchema,
+    /** The display label, never the value. */
+    label: z.string().max(200),
+    cipher: base64urlSchema,
+    wraps: z.record(keyIdSchema, base64urlSchema),
+    /** When the value was last set; rewraps keep it (plan decision 5). */
+    updatedAt: isoSchema,
+    /** The key that signed this version. */
+    updatedBy: keyIdSchema,
+    signature: signatureSchema,
+});
+export const TEAM_SECRETS_KEYS_DIR = `${TEAM_SECRETS_DIR}/keys`;
+export const TEAM_SECRETS_ACCESS_DIR = `${TEAM_SECRETS_DIR}/access`;
+export const TEAM_SECRETS_VALUES_DIR = `${TEAM_SECRETS_DIR}/values`;
+export function keyRequestPath(keyId) {
+    return `${TEAM_SECRETS_KEYS_DIR}/${keyId}.yaml`;
+}
+export function accessEntryPath(id) {
+    return `${TEAM_SECRETS_ACCESS_DIR}/${id}.yaml`;
+}
+export function vaultEntryPath(id) {
+    return `${TEAM_SECRETS_VALUES_DIR}/${id}.yaml`;
+}
+const TEAM_SECRETS_FILE = new RegExp(`^${TEAM_SECRETS_DIR}/(keys|access|values)/([0-9A-Z]{26})\\.yaml$`);
+export function isTeamSecretsPath(path) {
+    return TEAM_SECRETS_FILE.test(path);
+}
+export function isVaultEntryPath(path) {
+    return TEAM_SECRETS_FILE.exec(path)?.[1] === 'values';
+}
+export function vaultEntryIdOfPath(path) {
+    const match = TEAM_SECRETS_FILE.exec(path);
+    return match?.[1] === 'values' ? match[2] : undefined;
+}
+/** Plan decision 3: base32 of SHA-256 over `ref:<ref>` or `token:<projectId>\n<name>`, first 26 characters. */
+export function vaultEntryId(secret) {
+    const text = 'ref' in secret ? `ref:${secret.ref}` : `token:${secret.token.projectId}\n${secret.token.name}`;
+    return base32(createHash('sha256').update(text, 'utf8').digest()).slice(0, 26);
+}
+export function sameSecret(a, b) {
+    return vaultEntryId(a) === vaultEntryId(b);
+}
+export function teamSecretsFileText(doc) {
+    return stringifyYaml(doc);
+}
+export function parseTeamSecretsFile(schema, text) {
+    let parsed;
+    try {
+        parsed = parseYaml(text, 'team-secrets');
+    }
+    catch {
+        return undefined;
+    }
+    const result = schema.safeParse(parsed);
+    return result.success ? result.data : undefined;
+}
+/** Parses the tree's team-secrets files, given as tree path → text. Other paths are ignored. */
+export function readTeamSecretsFiles(files) {
+    const out = { keys: [], access: [], values: new Map(), invalid: [] };
+    for (const [path, text] of files) {
+        const match = TEAM_SECRETS_FILE.exec(path);
+        if (match === null) {
+            continue;
+        }
+        const [, kind, name] = match;
+        if (kind === 'keys') {
+            const doc = parseTeamSecretsFile(keyRequestFileSchema, text);
+            if (doc !== undefined && doc.keyId === name) {
+                out.keys.push(doc);
+            }
+            else {
+                out.invalid.push(path);
+            }
+        }
+        else if (kind === 'access') {
+            const doc = parseTeamSecretsFile(accessEntryFileSchema, text);
+            if (doc !== undefined && doc.id === name) {
+                out.access.push(doc);
+            }
+            else {
+                out.invalid.push(path);
+            }
+        }
+        else {
+            const doc = parseTeamSecretsFile(vaultEntryFileSchema, text);
+            if (doc !== undefined && name !== undefined && vaultEntryId(doc.secret) === name) {
+                out.values.set(name, doc);
+            }
+            else {
+                out.invalid.push(path);
+            }
+        }
+    }
+    return out;
+}

package/dist/team-secrets/sign.d.ts

@@ -0,0 +1,24 @@
+import { type MachineKeys } from './keys.js';
+export type Signed<T> = T & {
+    readonly signature: string;
+};
+/**
+ * Canonical JSON of `value`: object keys sorted at every depth, no whitespace, `undefined` values (object
+ * fields only, never array elements) dropped. Only JSON's own shapes are accepted — `null`, booleans,
+ * strings, finite numbers, arrays, and plain objects (prototype `Object.prototype` or `null`) — so a
+ * `Date`, `Map`, `Set`, class instance, function, symbol, `NaN` or `±Infinity` throws rather than silently
+ * signing something that would not round-trip through YAML the same way twice. `-0` is written as `0`
+ * (`JSON.stringify` already does this, and YAML has no distinct negative zero), which is deliberate, not
+ * an oversight.
+ *
+ * @throws WirebenchError `team-secrets-not-canonical`
+ */
+export declare function canonicalJson(value: unknown): string;
+/** A shallow copy of `doc` without its `signature` field. */
+export declare function withoutSignature(doc: object): Record<string, unknown>;
+/** `doc` with a fresh `signature` by `keys`; an existing signature is replaced. */
+export declare function signDocument<T extends object>(doc: T, keys: MachineKeys): Signed<T>;
+/** Whether `doc.signature` is `signingKey`'s signature over the rest of `doc`. Never throws. */
+export declare function verifyDocument<T extends {
+    readonly signature: string;
+}>(doc: T, signingKey: string): boolean;