@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/sync/three-way-merge.d.ts

@@ -0,0 +1,41 @@
+import type { ProjectFiles } from '../project/serialize.js';
+/** The outcome of laying one side's files back over the other's. */
+export interface FileMerge {
+    /** The files the merged tree should be read from. */
+    readonly files: ProjectFiles;
+    /**
+     * Changed on both sides; the `unsaved` (mine) version was kept — or, for a deletion on the
+     * `unsaved` side of a file that changed on `disk`, the disk version was. With `modifyDelete:
+     * 'conflict'`, also a change on the `unsaved` side of a file deleted on `disk`, whose unsaved
+     * version was kept.
+     */
+    readonly conflicts: readonly string[];
+    /** Changed on the `unsaved` side but deleted on `disk`; the change was dropped. Always empty with `modifyDelete: 'conflict'`. */
+    readonly dropped: readonly string[];
+    /** Whether the merged files differ from `disk` at all. */
+    readonly changed: boolean;
+}
+/** How {@link mergeFiles} treats a file changed on the `unsaved` side and deleted on `disk`. */
+export interface MergeFilesOptions {
+    /** 'drop' (default, unsaved-changes recovery): changed on the unsaved side, deleted on disk → dropped.
+     *  'conflict' (sync): the same case is a conflict, and the unsaved (mine) version is kept in `files`. */
+    readonly modifyDelete?: 'drop' | 'conflict';
+}
+/**
+ * Three-way merge, one file at a time, of the `baseline` (B) both sides started from, the files
+ * on `disk` (D, "theirs") and the `unsaved` files (U, "mine"):
+ *
+ * - U = B → D (only disk changed, or nothing did);
+ * - D = B → U (only the unsaved side changed — including an unsaved deletion);
+ * - both changed:
+ *   - D = U → U (the same change on both sides);
+ *   - deleted on disk → dropped (the file, e.g. a request, no longer exists) — or, with
+ *     `modifyDelete: 'conflict'`, U, flagged: sync must never lose a change silently, and git
+ *     calls this case a conflict too;
+ *   - deleted in the unsaved record → D, flagged (a change on disk beats an unsaved deletion);
+ *   - otherwise → U, flagged (unsaved changes are restored on top).
+ *
+ * Every value is compared whole, so the merge does not care what a value encodes (sync passes
+ * `encoding:content` strings).
+ */
+export declare function mergeFiles(baseline: ProjectFiles, disk: ProjectFiles, unsaved: ProjectFiles, options?: MergeFilesOptions): FileMerge;

package/dist/sync/three-way-merge.js

@@ -0,0 +1,85 @@
+/**
+ * A per-file three-way merge shared by the desktop's unsaved-changes recovery and the sync
+ * backends (the fake one in the desktop's tests, and `ServerBackend` for Wirebench Server). It lives
+ * in the engine so both run the same code — the point of ADR-0008's "one repository, two
+ * transports".
+ */
+import { MANIFEST_PATH } from '../project/serialize.js';
+/**
+ * The manifest records which save wrote it (`writtenBy: wirebench (manual)`), so two otherwise
+ * identical manifests differ after every save. That line is not a change anyone made.
+ */
+function comparable(path, content) {
+    if (content === undefined || path !== MANIFEST_PATH) {
+        return content;
+    }
+    return content
+        .split('\n')
+        .filter((line) => !/^writtenBy:/.test(line))
+        .join('\n');
+}
+function same(path, a, b) {
+    return comparable(path, a) === comparable(path, b);
+}
+/**
+ * Three-way merge, one file at a time, of the `baseline` (B) both sides started from, the files
+ * on `disk` (D, "theirs") and the `unsaved` files (U, "mine"):
+ *
+ * - U = B → D (only disk changed, or nothing did);
+ * - D = B → U (only the unsaved side changed — including an unsaved deletion);
+ * - both changed:
+ *   - D = U → U (the same change on both sides);
+ *   - deleted on disk → dropped (the file, e.g. a request, no longer exists) — or, with
+ *     `modifyDelete: 'conflict'`, U, flagged: sync must never lose a change silently, and git
+ *     calls this case a conflict too;
+ *   - deleted in the unsaved record → D, flagged (a change on disk beats an unsaved deletion);
+ *   - otherwise → U, flagged (unsaved changes are restored on top).
+ *
+ * Every value is compared whole, so the merge does not care what a value encodes (sync passes
+ * `encoding:content` strings).
+ */
+export function mergeFiles(baseline, disk, unsaved, options) {
+    const modifyDelete = options?.modifyDelete ?? 'drop';
+    const files = new Map();
+    const conflicts = [];
+    const dropped = [];
+    const paths = [...new Set([...baseline.keys(), ...disk.keys(), ...unsaved.keys()])].sort();
+    for (const path of paths) {
+        const b = baseline.get(path);
+        const d = disk.get(path);
+        const u = unsaved.get(path);
+        let take;
+        if (same(path, u, b)) {
+            take = d;
+        }
+        else if (same(path, d, b)) {
+            take = u;
+        }
+        else if (same(path, d, u)) {
+            take = u;
+        }
+        else if (d === undefined) {
+            if (modifyDelete === 'conflict') {
+                conflicts.push(path);
+                take = u;
+            }
+            else {
+                dropped.push(path);
+                take = undefined;
+            }
+        }
+        else if (u === undefined) {
+            conflicts.push(path);
+            take = d;
+        }
+        else {
+            conflicts.push(path);
+            take = u;
+        }
+        if (take !== undefined) {
+            files.set(path, take);
+        }
+    }
+    const changed = [...new Set([...files.keys(), ...disk.keys()])].some((path) => !same(path, files.get(path), disk.get(path)));
+    return { files, conflicts, dropped, changed };
+}

package/dist/sync/tree-paths.d.ts

@@ -0,0 +1,34 @@
+/** Everything that makes up a workspace tree, in the order a share moves them (formerly private to the desktop's workspace-share.ts). */
+export declare const TREE_ITEMS: readonly ["workspace.yaml", "environments", "projects", ".gitattributes", "team-secrets"];
+/** Longest tree path the sync accepts, in characters (§3.2). */
+export declare const MAX_TREE_PATH_LENGTH = 512;
+/**
+ * Machine-local names that never travel: 'share.yaml', 'local.yaml' and the 'unsaved' directory
+ * (the desktop's `UNSAVED_DIR`). They live beside the tree in a workspace's app-data folder, and a
+ * snapshot or a commit that carried one would leak one machine's state (and a secret-bearing
+ * recovery record) to every member.
+ */
+export declare const MACHINE_LOCAL_PATHS: readonly string[];
+/**
+ * Returns `path` when it is a relative, normalised, forward-slash tree path of at most 512
+ * characters: no '..', '.' or empty segment, no '.git' segment (in any spelling git refuses), no
+ * segment Windows cannot hold (a device name, a trailing dot or space, one of `<>:"|?*`), no
+ * backslash or control character, not absolute, not machine-local, whose first segment is one of
+ * TREE_ITEMS, and which names a file (`workspace.yaml` and `.gitattributes` stand alone; the three
+ * directories need something below them — and under `team-secrets/` specifically, exactly
+ * `keys/<id>.yaml`, `access/<id>.yaml` or `values/<id>.yaml`, per {@link isTeamSecretsPath}).
+ *
+ * @throws WirebenchError 'sync-path-refused' otherwise, with `details.reason` naming the rule and
+ * `details.path` the path, cut to {@link MAX_TREE_PATH_LENGTH} characters.
+ */
+export declare function assertTreePath(path: string): string;
+/** Whether {@link assertTreePath} would accept `path`. */
+export declare function isTreePath(path: string): boolean;
+/**
+ * Whether a single filesystem entry name (never a `/`-joined path) is one the tree rules refuse
+ * anywhere: empty, `.`/`..`, a control character, a `.git` spelling, or a Windows-unsafe name.
+ * Unlike {@link isTreePath} it never asks whether the name completes a valid tree path — a directory
+ * has no such thing — so a tree walk can prune an unsafe folder (a nested `.git`, say) before
+ * descending into it, rather than reading it and refusing every file inside one at a time.
+ */
+export declare function isSafeTreeSegment(segment: string): boolean;

package/dist/sync/tree-paths.js

@@ -0,0 +1,131 @@
+/**
+ * The rules a path in a synced workspace tree obeys (server-sync spec §3.2, §6). Wirebench Server
+ * checks every path a push names before any git call. The desktop checks every path a snapshot or a
+ * change names before it writes to disk. Both call {@link assertTreePath}, so both ends refuse
+ * exactly the same paths.
+ */
+import { WirebenchError } from '../errors.js';
+import { isTeamSecretsPath } from '../team-secrets/schema.js';
+import { WORKSPACE_LOCAL_FILE } from '../workspace/local-state.js';
+import { GIT_ATTRIBUTES_FILE, TEAM_SECRETS_DIR, WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST, WORKSPACE_PROJECTS_DIR, } from '../workspace/paths.js';
+import { WORKSPACE_SHARE_FILE } from '../workspace/share.js';
+/** Everything that makes up a workspace tree, in the order a share moves them (formerly private to the desktop's workspace-share.ts). */
+export const TREE_ITEMS = [
+    WORKSPACE_MANIFEST,
+    WORKSPACE_ENVIRONMENTS_DIR,
+    WORKSPACE_PROJECTS_DIR,
+    GIT_ATTRIBUTES_FILE,
+    TEAM_SECRETS_DIR,
+];
+/** The tree items that are single files. The other three are directories, so a path names a file below them. */
+const FILE_ITEMS = new Set([WORKSPACE_MANIFEST, GIT_ATTRIBUTES_FILE]);
+/** Longest tree path the sync accepts, in characters (§3.2). */
+export const MAX_TREE_PATH_LENGTH = 512;
+/**
+ * Machine-local names that never travel: 'share.yaml', 'local.yaml' and the 'unsaved' directory
+ * (the desktop's `UNSAVED_DIR`). They live beside the tree in a workspace's app-data folder, and a
+ * snapshot or a commit that carried one would leak one machine's state (and a secret-bearing
+ * recovery record) to every member.
+ */
+export const MACHINE_LOCAL_PATHS = [WORKSPACE_SHARE_FILE, WORKSPACE_LOCAL_FILE, 'unsaved'];
+/** C0 controls and DEL: git's `-z` output and `update-index` input cannot carry them faithfully. */
+const CONTROL_CHARACTER = /[\x00-\x1f\x7f]/;
+/** A POSIX root, or a Windows drive. */
+const ABSOLUTE = /^(?:\/|[A-Za-z]:)/;
+/**
+ * `.git` in any case, with the trailing dots or spaces Windows ignores, its 8.3 short name, and any
+ * of those followed by an NTFS alternate-data-stream suffix (`:$INDEX_ALLOCATION`, a bare `:`, or
+ * `git~1:x`) — every spelling git itself refuses in a tree under `core.protectNTFS`.
+ */
+const GIT_SEGMENT = /^(?:\.git|git~\d+)[. ]*(?::.*)?$/i;
+/**
+ * A segment Windows cannot hold: a reserved device name, with or without an extension (and with the
+ * spaces Windows ignores before it); a trailing dot or space, which Windows drops; or a character
+ * Windows refuses in a name. A Mac or Linux editor can create one, and once pushed it would stop
+ * every Windows teammate from opening the workspace, so both ends refuse it (`assertPathSegment`'s
+ * rules for the name part).
+ */
+const WINDOWS_UNSAFE_SEGMENT = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9]) *(?:\.|$)|[. ]$|[<>:"|?*]/i;
+function refusal(path) {
+    if (path.length === 0) {
+        return 'empty';
+    }
+    if (path.length > MAX_TREE_PATH_LENGTH) {
+        return 'too-long';
+    }
+    if (CONTROL_CHARACTER.test(path)) {
+        return 'control-character';
+    }
+    if (path.includes('\\')) {
+        return 'backslash';
+    }
+    if (ABSOLUTE.test(path)) {
+        return 'absolute';
+    }
+    const segments = path.split('/');
+    if (segments.some((segment) => segment.length === 0)) {
+        return 'empty-segment';
+    }
+    if (segments.some((segment) => segment === '.' || segment === '..')) {
+        return 'dot-segment';
+    }
+    if (segments.some((segment) => GIT_SEGMENT.test(segment))) {
+        return 'git-segment';
+    }
+    if (segments.some((segment) => WINDOWS_UNSAFE_SEGMENT.test(segment))) {
+        return 'windows-unsafe';
+    }
+    const first = segments[0] ?? '';
+    if (MACHINE_LOCAL_PATHS.includes(first)) {
+        return 'machine-local';
+    }
+    if (!TREE_ITEMS.includes(first)) {
+        return 'not-in-tree';
+    }
+    if (FILE_ITEMS.has(first) !== (segments.length === 1)) {
+        return 'not-a-file';
+    }
+    if (first === TEAM_SECRETS_DIR && !isTeamSecretsPath(path)) {
+        return 'not-a-file';
+    }
+    return undefined;
+}
+/**
+ * Returns `path` when it is a relative, normalised, forward-slash tree path of at most 512
+ * characters: no '..', '.' or empty segment, no '.git' segment (in any spelling git refuses), no
+ * segment Windows cannot hold (a device name, a trailing dot or space, one of `<>:"|?*`), no
+ * backslash or control character, not absolute, not machine-local, whose first segment is one of
+ * TREE_ITEMS, and which names a file (`workspace.yaml` and `.gitattributes` stand alone; the three
+ * directories need something below them — and under `team-secrets/` specifically, exactly
+ * `keys/<id>.yaml`, `access/<id>.yaml` or `values/<id>.yaml`, per {@link isTeamSecretsPath}).
+ *
+ * @throws WirebenchError 'sync-path-refused' otherwise, with `details.reason` naming the rule and
+ * `details.path` the path, cut to {@link MAX_TREE_PATH_LENGTH} characters.
+ */
+export function assertTreePath(path) {
+    const reason = refusal(path);
+    if (reason !== undefined) {
+        const shown = path.slice(0, MAX_TREE_PATH_LENGTH);
+        throw new WirebenchError('sync-path-refused', `${JSON.stringify(shown.slice(0, 120))} cannot be part of a shared workspace.`, { details: { path: shown, reason } });
+    }
+    return path;
+}
+/** Whether {@link assertTreePath} would accept `path`. */
+export function isTreePath(path) {
+    return refusal(path) === undefined;
+}
+/**
+ * Whether a single filesystem entry name (never a `/`-joined path) is one the tree rules refuse
+ * anywhere: empty, `.`/`..`, a control character, a `.git` spelling, or a Windows-unsafe name.
+ * Unlike {@link isTreePath} it never asks whether the name completes a valid tree path — a directory
+ * has no such thing — so a tree walk can prune an unsafe folder (a nested `.git`, say) before
+ * descending into it, rather than reading it and refusing every file inside one at a time.
+ */
+export function isSafeTreeSegment(segment) {
+    return (segment.length > 0 &&
+        segment !== '.' &&
+        segment !== '..' &&
+        !CONTROL_CHARACTER.test(segment) &&
+        !GIT_SEGMENT.test(segment) &&
+        !WINDOWS_UNSAFE_SEGMENT.test(segment));
+}

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

@@ -0,0 +1,10 @@
+import { type MachineKeys } from './keys.js';
+export declare const WRAP_INFO = "wirebench-team-secrets-v1-wrap";
+export declare function newDataKey(): Buffer;
+export declare function encryptValue(value: string, dataKey: Buffer, entryId: string): string;
+/** @throws WirebenchError `team-secrets-decrypt-failed` | `team-secrets-bad-key` */
+export declare function decryptValue(cipher: string, dataKey: Buffer, entryId: string): string;
+/** @throws WirebenchError `team-secrets-bad-key` */
+export declare function wrapDataKey(dataKey: Buffer, recipientEncryptionKey: string): string;
+/** @throws WirebenchError `team-secrets-decrypt-failed` | `team-secrets-bad-key` */
+export declare function unwrapDataKey(wrap: string, keys: MachineKeys): Buffer;

package/dist/team-secrets/envelope.js

@@ -0,0 +1,121 @@
+/**
+ * The vault envelope (§4): a value is encrypted once with a random data key (AES-256-GCM, the vault entry id
+ * as additional data, so a cipher cannot be moved to another secret), and the data key is wrapped for each
+ * approved machine. A wrap is a fresh ephemeral X25519 public key, a nonce and the sealed data key; the
+ * sealing key is HKDF-SHA256 of the ECDH secret, salted with both public keys.
+ *
+ * Every binary field is base64url: `nonce || ciphertext || tag` for a cipher, `ephemeral || nonce ||
+ * sealed || tag` for a wrap.
+ */
+import { createCipheriv, createDecipheriv, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from 'node:crypto';
+import { WirebenchError } from '../errors.js';
+import { teamSecretsError } from './errors.js';
+import { base64url, encryptionPrivateKey, encryptionPublicKey, fromBase64url } from './keys.js';
+export const WRAP_INFO = 'wirebench-team-secrets-v1-wrap';
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const PUBLIC_KEY_BYTES = 32;
+function failed(cause) {
+    return teamSecretsError('team-secrets-decrypt-failed', cause !== undefined ? { cause } : undefined);
+}
+/** A malformed or out-of-range key or data key. Never carries the offending key material. */
+function badKey() {
+    return teamSecretsError('team-secrets-bad-key');
+}
+function seal(key, plaintext, aad) {
+    const nonce = randomBytes(NONCE_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    if (aad !== undefined) {
+        cipher.setAAD(aad);
+    }
+    const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return Buffer.concat([nonce, body, cipher.getAuthTag()]);
+}
+function open(key, sealed, aad) {
+    if (sealed.length < NONCE_BYTES + TAG_BYTES) {
+        throw failed();
+    }
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, sealed.subarray(0, NONCE_BYTES));
+        if (aad !== undefined) {
+            decipher.setAAD(aad);
+        }
+        decipher.setAuthTag(sealed.subarray(sealed.length - TAG_BYTES));
+        return Buffer.concat([decipher.update(sealed.subarray(NONCE_BYTES, sealed.length - TAG_BYTES)), decipher.final()]);
+    }
+    catch (error) {
+        throw failed(error);
+    }
+}
+export function newDataKey() {
+    return randomBytes(KEY_BYTES);
+}
+/** @throws WirebenchError `team-secrets-bad-key` if `dataKey` is not exactly 32 bytes. */
+function assertDataKey(dataKey) {
+    if (dataKey.length !== KEY_BYTES) {
+        throw badKey();
+    }
+}
+/**
+ * A recipient's X25519 public key as a `KeyObject`, and the ECDH secret computed with it. Throws
+ * `team-secrets-bad-key` for anything that is not a well-formed, non-degenerate point: malformed
+ * base64url, the wrong length, or a low-order point whose shared secret is all-zero — never the raw
+ * `TypeError`/`RangeError`/OpenSSL error, and never the key material itself.
+ */
+function sharedSecretWith(privateKey, recipientRaw) {
+    let publicKey;
+    try {
+        publicKey = encryptionPublicKey(recipientRaw);
+    }
+    catch {
+        throw badKey();
+    }
+    let shared;
+    try {
+        shared = diffieHellman({ privateKey, publicKey });
+    }
+    catch {
+        throw badKey();
+    }
+    if (shared.equals(Buffer.alloc(shared.length))) {
+        // A low-order point collapses ECDH to an all-zero secret regardless of the private key.
+        throw badKey();
+    }
+    return shared;
+}
+export function encryptValue(value, dataKey, entryId) {
+    assertDataKey(dataKey);
+    return base64url(seal(dataKey, Buffer.from(value, 'utf8'), Buffer.from(entryId, 'utf8')));
+}
+/** @throws WirebenchError `team-secrets-decrypt-failed` | `team-secrets-bad-key` */
+export function decryptValue(cipher, dataKey, entryId) {
+    assertDataKey(dataKey);
+    return open(dataKey, fromBase64url(cipher), Buffer.from(entryId, 'utf8')).toString('utf8');
+}
+function wrapKey(shared, ephemeral, recipient) {
+    return Buffer.from(hkdfSync('sha256', shared, Buffer.concat([ephemeral, recipient]), WRAP_INFO, KEY_BYTES));
+}
+/** @throws WirebenchError `team-secrets-bad-key` */
+export function wrapDataKey(dataKey, recipientEncryptionKey) {
+    assertDataKey(dataKey);
+    const pair = generateKeyPairSync('x25519');
+    const ephemeral = fromBase64url(String(pair.publicKey.export({ format: 'jwk' }).x));
+    const shared = sharedSecretWith(pair.privateKey, recipientEncryptionKey);
+    const key = wrapKey(shared, ephemeral, fromBase64url(recipientEncryptionKey));
+    return base64url(Buffer.concat([ephemeral, seal(key, dataKey)]));
+}
+/** @throws WirebenchError `team-secrets-decrypt-failed` | `team-secrets-bad-key` */
+export function unwrapDataKey(wrap, keys) {
+    const bytes = fromBase64url(wrap);
+    if (bytes.length < PUBLIC_KEY_BYTES + NONCE_BYTES + TAG_BYTES) {
+        throw failed();
+    }
+    const ephemeral = bytes.subarray(0, PUBLIC_KEY_BYTES);
+    const shared = sharedSecretWith(encryptionPrivateKey(keys), base64url(ephemeral));
+    const dataKey = open(wrapKey(shared, ephemeral, fromBase64url(keys.encryptionKey)), bytes.subarray(PUBLIC_KEY_BYTES));
+    if (dataKey.length !== KEY_BYTES) {
+        throw failed();
+    }
+    return dataKey;
+}

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

@@ -0,0 +1,26 @@
+import { WirebenchError } from '../errors.js';
+/** The user-facing team-secrets failures (spec §3.8), one message each. */
+export declare const TEAM_SECRETS_MESSAGES: {
+    readonly 'team-secrets-pending': "This machine is waiting for an admin to approve it for team secrets.";
+    readonly 'team-secrets-removed': "An admin removed this machine from team secrets.";
+    readonly 'team-secrets-declined': "An admin declined this machine's request for team secrets.";
+    readonly 'team-secrets-no-safe-storage': "Team secrets need the system keychain, which is not available on this machine.";
+    readonly 'team-secrets-admin-only': "Only a workspace admin can change who has access to team secrets.";
+    readonly 'team-secrets-untrusted': "Ignored a secret signed by a key that is not approved.";
+    readonly 'team-secrets-last-admin': "A workspace needs at least one admin for team secrets.";
+    readonly 'team-secrets-not-canonical': "A team secrets document contained a value that could not be signed.";
+    readonly 'team-secrets-bad-key': "A team secrets key was malformed.";
+    readonly 'team-secrets-decrypt-failed': "A team secret could not be decrypted.";
+    readonly 'team-secrets-not-shared': "Team secrets need a shared workspace.";
+    readonly 'team-secrets-no-such-key': "That machine is not waiting for approval, or not approved, as this change needs.";
+    readonly 'team-secrets-server-authority': "On a server workspace, the server roles decide who is an admin.";
+    readonly 'team-secrets-remove-self': "Ask another admin to remove this machine.";
+    readonly 'team-secrets-cannot-reencrypt': "Some team secrets are not readable on this machine, so they cannot be re-encrypted. Ask another admin to remove this machine, or wait for this machine to receive them.";
+    readonly 'team-secrets-already-admin': "That machine is already a team secrets admin.";
+    readonly 'team-secrets-not-admin': "That machine is not a team secrets admin.";
+    readonly 'team-secrets-last-approved': "A workspace needs at least one approved machine for team secrets.";
+    readonly 'team-secrets-not-allowed': "That change to team secrets access is not allowed.";
+    readonly 'team-secrets-damaged': "The team secrets access log on this machine does not match what it saw before; this machine will not change team secrets until it is repaired.";
+};
+export type TeamSecretsErrorCode = keyof typeof TEAM_SECRETS_MESSAGES;
+export declare function teamSecretsError(code: TeamSecretsErrorCode, details?: Readonly<Record<string, unknown>>): WirebenchError;

package/dist/team-secrets/errors.js

@@ -0,0 +1,27 @@
+import { WirebenchError } from '../errors.js';
+/** The user-facing team-secrets failures (spec §3.8), one message each. */
+export const TEAM_SECRETS_MESSAGES = {
+    'team-secrets-pending': 'This machine is waiting for an admin to approve it for team secrets.',
+    'team-secrets-removed': 'An admin removed this machine from team secrets.',
+    'team-secrets-declined': "An admin declined this machine's request for team secrets.",
+    'team-secrets-no-safe-storage': 'Team secrets need the system keychain, which is not available on this machine.',
+    'team-secrets-admin-only': 'Only a workspace admin can change who has access to team secrets.',
+    'team-secrets-untrusted': 'Ignored a secret signed by a key that is not approved.',
+    'team-secrets-last-admin': 'A workspace needs at least one admin for team secrets.',
+    'team-secrets-not-canonical': 'A team secrets document contained a value that could not be signed.',
+    'team-secrets-bad-key': 'A team secrets key was malformed.',
+    'team-secrets-decrypt-failed': 'A team secret could not be decrypted.',
+    'team-secrets-not-shared': 'Team secrets need a shared workspace.',
+    'team-secrets-no-such-key': 'That machine is not waiting for approval, or not approved, as this change needs.',
+    'team-secrets-server-authority': 'On a server workspace, the server roles decide who is an admin.',
+    'team-secrets-remove-self': 'Ask another admin to remove this machine.',
+    'team-secrets-cannot-reencrypt': 'Some team secrets are not readable on this machine, so they cannot be re-encrypted. Ask another admin to remove this machine, or wait for this machine to receive them.',
+    'team-secrets-already-admin': 'That machine is already a team secrets admin.',
+    'team-secrets-not-admin': 'That machine is not a team secrets admin.',
+    'team-secrets-last-approved': 'A workspace needs at least one approved machine for team secrets.',
+    'team-secrets-not-allowed': 'That change to team secrets access is not allowed.',
+    'team-secrets-damaged': 'The team secrets access log on this machine does not match what it saw before; this machine will not change team secrets until it is repaired.',
+};
+export function teamSecretsError(code, details) {
+    return new WirebenchError(code, TEAM_SECRETS_MESSAGES[code], details !== undefined ? { details } : undefined);
+}

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

@@ -0,0 +1,14 @@
+export { decryptValue, encryptValue, newDataKey, unwrapDataKey, WRAP_INFO, wrapDataKey } from './envelope.js';
+export { TEAM_SECRETS_MESSAGES, teamSecretsError } from './errors.js';
+export type { TeamSecretsErrorCode } from './errors.js';
+export { base32, base64url, encryptionPrivateKey, encryptionPublicKey, fingerprintOf, fromBase64url, generateMachineKeys, KEY_ID_PATTERN, keyIdOf, parseMachineKeys, serializeMachineKeys, signingPrivateKey, signingPublicKey, } from './keys.js';
+export type { MachineKeys, MachinePublicKeys } from './keys.js';
+export { nextAccessEntryId, replayAccessLog, verifiedKeys } from './log.js';
+export type { AccessState, KeyInfo, LogProblem, Removal } from './log.js';
+export { vaultConflictWinner } from './resolve-conflict.js';
+export { ACCESS_ACTIONS, accessEntryFileSchema, accessEntryPath, isTeamSecretsPath, isVaultEntryPath, keyIdSchema, keyRequestFileSchema, keyRequestPath, parseTeamSecretsFile, readTeamSecretsFiles, sameSecret, secretKeySchema, TEAM_SECRETS_ACCESS_DIR, TEAM_SECRETS_FORMAT_VERSION, TEAM_SECRETS_KEYS_DIR, TEAM_SECRETS_VALUES_DIR, teamSecretsFileText, ULID_PATTERN, vaultEntryFileSchema, vaultEntryId, vaultEntryIdOfPath, vaultEntryPath, } from './schema.js';
+export type { AccessAction, AccessEntryFile, KeyRequestFile, SecretKey, TeamSecretsFiles, VaultEntryFile, } from './schema.js';
+export { canonicalJson, signDocument, verifyDocument, withoutSignature } from './sign.js';
+export type { Signed } from './sign.js';
+export { approvedRecipients, buildVaultEntry, healVaultEntry, openVaultEntry, rotateMarks, rotateMarksFor, sealVaultEntry, verifyVaultEntry, wrapsUnapprovedKey, } from './vault.js';
+export type { RotateMark, VaultVerdict } from './vault.js';

package/dist/team-secrets/index.js

@@ -0,0 +1,8 @@
+export { decryptValue, encryptValue, newDataKey, unwrapDataKey, WRAP_INFO, wrapDataKey } from './envelope.js';
+export { TEAM_SECRETS_MESSAGES, teamSecretsError } from './errors.js';
+export { base32, base64url, encryptionPrivateKey, encryptionPublicKey, fingerprintOf, fromBase64url, generateMachineKeys, KEY_ID_PATTERN, keyIdOf, parseMachineKeys, serializeMachineKeys, signingPrivateKey, signingPublicKey, } from './keys.js';
+export { nextAccessEntryId, replayAccessLog, verifiedKeys } from './log.js';
+export { vaultConflictWinner } from './resolve-conflict.js';
+export { ACCESS_ACTIONS, accessEntryFileSchema, accessEntryPath, isTeamSecretsPath, isVaultEntryPath, keyIdSchema, keyRequestFileSchema, keyRequestPath, parseTeamSecretsFile, readTeamSecretsFiles, sameSecret, secretKeySchema, TEAM_SECRETS_ACCESS_DIR, TEAM_SECRETS_FORMAT_VERSION, TEAM_SECRETS_KEYS_DIR, TEAM_SECRETS_VALUES_DIR, teamSecretsFileText, ULID_PATTERN, vaultEntryFileSchema, vaultEntryId, vaultEntryIdOfPath, vaultEntryPath, } from './schema.js';
+export { canonicalJson, signDocument, verifyDocument, withoutSignature } from './sign.js';
+export { approvedRecipients, buildVaultEntry, healVaultEntry, openVaultEntry, rotateMarks, rotateMarksFor, sealVaultEntry, verifyVaultEntry, wrapsUnapprovedKey, } from './vault.js';

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

@@ -0,0 +1,52 @@
+/**
+ * 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 { type KeyObject } from 'node:crypto';
+/** A key id: the first 26 base32 characters of SHA-256 over both public keys. */
+export declare const KEY_ID_PATTERN: RegExp;
+/** The two public keys a key request publishes. */
+export interface MachinePublicKeys {
+    /** X25519, base64url of 32 bytes. */
+    readonly encryptionKey: string;
+    /** Ed25519, base64url of 32 bytes. */
+    readonly signingKey: string;
+}
+/** A machine's full key set. The private halves never leave the desktop's main process. */
+export interface MachineKeys extends MachinePublicKeys {
+    readonly keyId: string;
+    readonly encryptionPrivate: string;
+    readonly signingPrivate: string;
+}
+export declare function base64url(bytes: Uint8Array): string;
+/**
+ * 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 declare function fromBase64url(text: string): Buffer;
+/** RFC 4648 base32 without padding. */
+export declare function base32(bytes: Uint8Array): string;
+export declare function keyIdOf(keys: MachinePublicKeys): string;
+/** What an admin reads out to the person (§3.2): the first 16 hex of the same digest, in groups of four. */
+export declare function fingerprintOf(keys: MachinePublicKeys): string;
+export declare function generateMachineKeys(): MachineKeys;
+export declare function encryptionPublicKey(raw: string): KeyObject;
+export declare function encryptionPrivateKey(keys: MachineKeys): KeyObject;
+export declare function signingPublicKey(raw: string): KeyObject;
+export declare function signingPrivateKey(keys: MachineKeys): KeyObject;
+/** The stored form, kept in the keychain-backed store only. */
+export declare function serializeMachineKeys(keys: MachineKeys): string;
+/**
+ * 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 declare function parseMachineKeys(text: string): MachineKeys | undefined;