@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/server-api/live.js

@@ -0,0 +1,102 @@
+/**
+ * The live-updates protocol (live-updates spec §3.1, §4): one WebSocket at `GET /api/v1/live`, one
+ * UTF-8 JSON text message per frame. The server's socket loop parses client messages with
+ * {@link liveClientMessageSchema} and the desktop's `LiveClient` parses server messages with
+ * {@link liveServerMessageSchema}, so a drift between the two fails typecheck.
+ *
+ * Plain zod only (ADR-0009). Tokens are on `DEVICE_TOKEN_PATTERN`, workspace ids on `TEAMS_ID_PATTERN`,
+ * user ids on `identityIdSchema` and heads on `SYNC_COMMIT_ID_PATTERN`. No message carries a role, an
+ * email or file content (§6):
+ * HTTP stays the source of truth, and a message only ever says "ask again".
+ *
+ * The server union is closed on purpose. `LiveClient` skips a `type` it does not know before it parses
+ * (§3.1, *Unknown types*), so a newer server can add a message without breaking an older app. zod's
+ * default strip drops unknown fields from a known message for the same reason.
+ */
+import { z } from 'zod';
+import { DEVICE_TOKEN_PATTERN, identityIdSchema } from './identity.js';
+import { syncCommitIdSchema } from './sync.js';
+import { teamsIdSchema } from './teams.js';
+/** §3.3's limits, shared so the desktop never sends what the server would refuse. */
+export const LIVE_LIMITS = {
+    /** A client message's largest size (`maxPayload`); a larger one closes `1009`. Server messages are not capped. */
+    maxMessageBytes: 4096,
+    /** Across every socket of one device token; the next subscribe is `refused … live-too-many-subscriptions`. */
+    maxSubscriptionsPerSession: 200,
+    /** Authenticated sockets per user; the next one closes `4429`. */
+    maxSocketsPerUser: 32,
+    /** How long a socket may wait before its `auth` (then `4408`), and how long the desktop waits for `ready` or `pong`. */
+    authTimeoutMs: 10_000,
+    /** The server's protocol-ping interval, and the desktop's `ping` interval. */
+    heartbeatMs: 30_000,
+};
+/**
+ * The close codes of §3.1. `1000`–`1011` are the protocol's own. The `44xx` codes mirror the HTTP
+ * status each stands for. Only `4401` stops the desktop from reconnecting: it runs the token check
+ * instead.
+ */
+export const LIVE_CLOSE = {
+    /** The desktop closed it: no open workspace on that server, sign-out, or quit. */
+    normal: 1000,
+    /** The server is shutting down; the desktop reconnects with back-off. */
+    goingAway: 1001,
+    /** A client message over `LIVE_LIMITS.maxMessageBytes`. */
+    tooBig: 1009,
+    /** An unexpected server error on this socket. */
+    serverError: 1011,
+    /** A malformed or out-of-order message, or a binary frame. */
+    badMessage: 4400,
+    /** A bad token, an ended session, or the token's maximum age reached. */
+    unauthenticated: 4401,
+    /** No `auth` within `LIVE_LIMITS.authTimeoutMs`. */
+    authTimeout: 4408,
+    /** The user already has `LIVE_LIMITS.maxSocketsPerUser` sockets; the desktop waits 60 s. */
+    tooManySockets: 4429,
+};
+/** The `capabilities` entry of `GET /api/v1/meta` that says a server serves {@link LIVE_PATH}. */
+export const LIVE_CAPABILITY = 'live';
+/** The socket's path on the server's origin. */
+export const LIVE_PATH = '/api/v1/live';
+/** Why a subscribe was refused. `teams-workspace-not-found` also means "no access", as HTTP does, so an id reveals nothing. */
+export const LIVE_REFUSED_CODES = ['teams-workspace-not-found', 'live-too-many-subscriptions'];
+/**
+ * One user with a subscribed socket on a workspace: an id and a display name, never an email (§6).
+ * - `id` is `identityIdSchema`: bounded in length and otherwise opaque, as HTTP treats user ids. Nothing
+ *   on the client uses it as a path or a storage key, and the e2e fake's ids are `u-<email>`.
+ * - `name` is the user's display name, which is never empty.
+ */
+export const livePresenceUserSchema = z.object({ id: identityIdSchema, name: z.string().min(1) });
+/** Client → server (§3.1). `auth` comes first, within `authTimeoutMs`, and the token travels nowhere else. */
+export const liveClientMessageSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('auth'), token: z.string().regex(DEVICE_TOKEN_PATTERN) }),
+    z.object({ type: z.literal('subscribe'), workspaceId: teamsIdSchema }),
+    z.object({ type: z.literal('unsubscribe'), workspaceId: teamsIdSchema }),
+    z.object({ type: z.literal('ping') }),
+]);
+/**
+ * Server → client (§3.1, R6).
+ * - `ready` answers a valid `auth` and `pong` answers `ping`. Together they let the desktop tell
+ *   *connecting* from *connected*, and a dead server from a quiet one.
+ * - `presence` includes the recipient, whom the desktop removes.
+ * - `session-ended` is always followed by a `4401` close.
+ * - `capture` and `hooks` (webhook-capture spec §3.6) say "a catch URL of this workspace caught
+ *   something" and "the workspace's catch URLs changed". Like every message they carry ids only; the
+ *   desktop fetches. The hub sends at most one `capture` per catch URL every 250 ms, carrying the
+ *   newest id. An app older than them skips both types.
+ */
+export const liveServerMessageSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('ready') }),
+    z.object({ type: z.literal('head'), workspaceId: teamsIdSchema, head: syncCommitIdSchema }),
+    z.object({ type: z.literal('access'), workspaceId: teamsIdSchema }),
+    z.object({ type: z.literal('presence'), workspaceId: teamsIdSchema, users: z.array(livePresenceUserSchema) }),
+    z.object({ type: z.literal('refused'), workspaceId: teamsIdSchema, code: z.enum(LIVE_REFUSED_CODES) }),
+    z.object({ type: z.literal('session-ended') }),
+    z.object({ type: z.literal('pong') }),
+    z.object({
+        type: z.literal('capture'),
+        workspaceId: teamsIdSchema,
+        hookId: teamsIdSchema,
+        captureId: teamsIdSchema,
+    }),
+    z.object({ type: z.literal('hooks'), workspaceId: teamsIdSchema }),
+]);

package/dist/server-api/meta.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What `GET /api/v1/meta` answers (host spec §3.2). Shared with the desktop so the Sign in
+ * dialog can tell a Wirebench Server from any other host by shape, not by guesswork.
+ */
+import { z } from 'zod';
+export declare const SERVER_NAME = "wirebench-server";
+export declare const SERVER_API_VERSION = 1;
+export declare const metaResponseSchema: z.ZodObject<{
+    name: z.ZodLiteral<"wirebench-server">;
+    version: z.ZodString;
+    apiVersion: z.ZodLiteral<1>;
+    publicUrl: z.ZodString;
+    auth: z.ZodObject<{
+        local: z.ZodBoolean;
+        oidc: z.ZodBoolean;
+        oidcDisplayName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    capabilities: z.ZodArray<z.ZodString>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        bodyLimitBytes: z.ZodNumber;
+        keep: z.ZodNumber;
+        maxAgeDays: z.ZodNumber;
+    }, z.core.$strip>>;
+    edition: z.ZodOptional<z.ZodEnum<{
+        community: "community";
+        team: "team";
+        enterprise: "enterprise";
+    }>>;
+}, z.core.$strip>;
+export type MetaResponse = z.infer<typeof metaResponseSchema>;

package/dist/server-api/meta.js

@@ -0,0 +1,21 @@
+/**
+ * What `GET /api/v1/meta` answers (host spec §3.2). Shared with the desktop so the Sign in
+ * dialog can tell a Wirebench Server from any other host by shape, not by guesswork.
+ */
+import { z } from 'zod';
+import { hooksMetaSchema } from './hooks.js';
+import { editionSchema } from './licensing.js';
+export const SERVER_NAME = 'wirebench-server';
+export const SERVER_API_VERSION = 1;
+export const metaResponseSchema = z.object({
+    name: z.literal(SERVER_NAME),
+    version: z.string(),
+    apiVersion: z.literal(SERVER_API_VERSION),
+    publicUrl: z.string().url(),
+    auth: z.object({ local: z.boolean(), oidc: z.boolean(), oidcDisplayName: z.string().optional() }),
+    capabilities: z.array(z.string()),
+    /** webhook-capture §3.7: absent on a server without the module, which the desktop reads as disabled. */
+    hooks: hooksMetaSchema.optional(),
+    /** licensing §3.6: the server's edition, and nothing else about its license. Absent from an older server. */
+    edition: editionSchema.optional(),
+});

package/dist/server-api/sync.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The server-sync module's wire shapes (server-sync spec §3.2, §4.4). The server's routes validate
+ * with them (through `jsonSchema()`) and the desktop's `ServerClient` parses answers with them, so a
+ * drift between the two fails typecheck.
+ *
+ * Plain zod only, with no refine or transform: the routes render these as draft-07 JSON Schema,
+ * which can carry neither. The rules JSON Schema cannot express run in the handler (and, for
+ * paths, in the client too):
+ * - tree paths (`assertTreePath`);
+ * - base64 and UTF-8 validity;
+ * - the per-file limit of {@link MAX_SYNC_FILE_BYTES}.
+ */
+import { z } from 'zod';
+/**
+ * A full git object id: 40 hex (SHA-1) or 64 hex (SHA-256), lower case. Every commit id in a query
+ * or a body matches this before it reaches git, so nothing a client sends can become a git option
+ * (`--upload-pack=…`) or a revision expression (`HEAD~1`, `main`).
+ */
+export declare const SYNC_COMMIT_ID_PATTERN: RegExp;
+/** The largest single file a snapshot, a change list or a push may carry, decoded (§3.2). */
+export declare const MAX_SYNC_FILE_BYTES: number;
+/** The most entries one `GET …/sync/log` returns (§3.2). */
+export declare const MAX_SYNC_LOG_LIMIT = 200;
+/** The longest commit subject a push may carry. */
+export declare const MAX_SYNC_SUBJECT_LENGTH = 1000;
+export declare const syncCommitIdSchema: z.ZodString;
+/** `utf8`: the content is the text itself. `base64`: the content is the bytes, for anything not valid UTF-8. */
+export declare const syncEncodingSchema: z.ZodEnum<{
+    utf8: "utf8";
+    base64: "base64";
+}>;
+export type SyncEncoding = z.infer<typeof syncEncodingSchema>;
+/** One file of a tree. */
+export declare const syncFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    encoding: z.ZodEnum<{
+        utf8: "utf8";
+        base64: "base64";
+    }>;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type SyncFile = z.infer<typeof syncFileSchema>;
+/** One path that differs; `content: null` means the file was deleted. */
+export declare const syncChangeSchema: z.ZodObject<{
+    path: z.ZodString;
+    encoding: z.ZodEnum<{
+        utf8: "utf8";
+        base64: "base64";
+    }>;
+    content: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SyncChange = z.infer<typeof syncChangeSchema>;
+/** `GET …/sync/head?from=`: `from` is the client's base, to count how far behind it is. */
+export declare const syncHeadQuerySchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SyncHeadQuery = z.infer<typeof syncHeadQuerySchema>;
+export declare const syncHeadResponseSchema: z.ZodObject<{
+    head: z.ZodNullable<z.ZodString>;
+    commits: z.ZodNumber;
+    behind: z.ZodOptional<z.ZodNumber>;
+    role: z.ZodEnum<{
+        editor: "editor";
+        admin: "admin";
+        viewer: "viewer";
+    }>;
+    recordDesktopActivity: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SyncHeadResponse = z.infer<typeof syncHeadResponseSchema>;
+/** `GET …/sync/snapshot?at=`: `at` defaults to the head. */
+export declare const syncSnapshotQuerySchema: z.ZodObject<{
+    at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SyncSnapshotQuery = z.infer<typeof syncSnapshotQuerySchema>;
+export declare const syncSnapshotResponseSchema: z.ZodObject<{
+    head: z.ZodNullable<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        encoding: z.ZodEnum<{
+            utf8: "utf8";
+            base64: "base64";
+        }>;
+        content: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SyncSnapshotResponse = z.infer<typeof syncSnapshotResponseSchema>;
+/** `GET …/sync/changes?from=&to=`: an absent `from` means the empty tree. */
+export declare const syncChangesQuerySchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodString;
+}, z.core.$strip>;
+export type SyncChangesQuery = z.infer<typeof syncChangesQuerySchema>;
+export declare const syncChangesResponseSchema: z.ZodObject<{
+    from: z.ZodNullable<z.ZodString>;
+    to: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        encoding: z.ZodEnum<{
+            utf8: "utf8";
+            base64: "base64";
+        }>;
+        content: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SyncChangesResponse = z.infer<typeof syncChangesResponseSchema>;
+/** One pending commit. The server authors it as the caller; `at` becomes the author date. */
+export declare const syncPushCommitSchema: z.ZodObject<{
+    subject: z.ZodString;
+    at: z.ZodISODateTime;
+    changes: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        encoding: z.ZodEnum<{
+            utf8: "utf8";
+            base64: "base64";
+        }>;
+        content: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SyncPushCommit = z.infer<typeof syncPushCommitSchema>;
+/** `POST …/sync/commits`: `parent` must be the current head (`null` for an empty workspace), or the push is rejected. */
+export declare const syncPushRequestSchema: z.ZodObject<{
+    parent: z.ZodNullable<z.ZodString>;
+    commits: z.ZodArray<z.ZodObject<{
+        subject: z.ZodString;
+        at: z.ZodISODateTime;
+        changes: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            content: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SyncPushRequest = z.infer<typeof syncPushRequestSchema>;
+/** `201`: the new head, and one id per pushed commit, in order. */
+export declare const syncPushResponseSchema: z.ZodObject<{
+    head: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type SyncPushResponse = z.infer<typeof syncPushResponseSchema>;
+/** `GET …/sync/log?limit=`. Fastify's Ajv coerces the querystring, so the handler reads a number. */
+export declare const syncLogQuerySchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SyncLogQuery = z.infer<typeof syncLogQuerySchema>;
+/**
+ * One commit, newest first. `author` is `Name <email>`. `at` is git's strict ISO author date,
+ * passed on as is: its UTC spelling differs between git versions, so it is not checked as a format.
+ */
+export declare const syncLogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    subject: z.ZodString;
+    author: z.ZodString;
+    at: z.ZodString;
+}, z.core.$strip>;
+export type SyncLogEntry = z.infer<typeof syncLogEntrySchema>;
+export declare const syncLogResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    subject: z.ZodString;
+    author: z.ZodString;
+    at: z.ZodString;
+}, z.core.$strip>>;
+/** The most a key request's file may hold, in UTF-8 bytes. */
+export declare const TEAM_SECRETS_KEY_REQUEST_MAX_BYTES = 4096;
+/**
+ * `POST …/team-secrets/key-requests`: `content` is the key file's text as the app wrote it. The server
+ * derives the path from `keyId` and never parses `content` (plan decision 11).
+ */
+export declare const teamSecretsKeyRequestSchema: z.ZodObject<{
+    keyId: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type TeamSecretsKeyRequest = z.infer<typeof teamSecretsKeyRequestSchema>;
+export declare const teamSecretsKeyRequestResponseSchema: z.ZodObject<{
+    head: z.ZodString;
+}, z.core.$strip>;
+export type TeamSecretsKeyRequestResponse = z.infer<typeof teamSecretsKeyRequestResponseSchema>;

package/dist/server-api/sync.js

@@ -0,0 +1,124 @@
+/**
+ * The server-sync module's wire shapes (server-sync spec §3.2, §4.4). The server's routes validate
+ * with them (through `jsonSchema()`) and the desktop's `ServerClient` parses answers with them, so a
+ * drift between the two fails typecheck.
+ *
+ * Plain zod only, with no refine or transform: the routes render these as draft-07 JSON Schema,
+ * which can carry neither. The rules JSON Schema cannot express run in the handler (and, for
+ * paths, in the client too):
+ * - tree paths (`assertTreePath`);
+ * - base64 and UTF-8 validity;
+ * - the per-file limit of {@link MAX_SYNC_FILE_BYTES}.
+ */
+import { z } from 'zod';
+import { KEY_ID_PATTERN } from '../team-secrets/keys.js';
+import { MAX_TREE_PATH_LENGTH } from '../sync/tree-paths.js';
+import { workspaceRoleSchema } from './teams.js';
+/**
+ * A full git object id: 40 hex (SHA-1) or 64 hex (SHA-256), lower case. Every commit id in a query
+ * or a body matches this before it reaches git, so nothing a client sends can become a git option
+ * (`--upload-pack=…`) or a revision expression (`HEAD~1`, `main`).
+ */
+export const SYNC_COMMIT_ID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+/** The largest single file a snapshot, a change list or a push may carry, decoded (§3.2). */
+export const MAX_SYNC_FILE_BYTES = 8 * 1024 * 1024;
+/** The most entries one `GET …/sync/log` returns (§3.2). */
+export const MAX_SYNC_LOG_LIMIT = 200;
+/** The longest commit subject a push may carry. */
+export const MAX_SYNC_SUBJECT_LENGTH = 1000;
+export const syncCommitIdSchema = z.string().regex(SYNC_COMMIT_ID_PATTERN);
+/** `utf8`: the content is the text itself. `base64`: the content is the bytes, for anything not valid UTF-8. */
+export const syncEncodingSchema = z.enum(['utf8', 'base64']);
+/** A tree path on the wire. Its rules beyond length are `assertTreePath`'s, run in the handler and the client. */
+const syncPathSchema = z.string().min(1).max(MAX_TREE_PATH_LENGTH);
+/** One file of a tree. */
+export const syncFileSchema = z.object({
+    path: syncPathSchema,
+    encoding: syncEncodingSchema,
+    content: z.string(),
+});
+/** One path that differs; `content: null` means the file was deleted. */
+export const syncChangeSchema = z.object({
+    path: syncPathSchema,
+    encoding: syncEncodingSchema,
+    content: z.string().nullable(),
+});
+// ---- head --------------------------------------------------------------------------------
+/** `GET …/sync/head?from=`: `from` is the client's base, to count how far behind it is. */
+export const syncHeadQuerySchema = z.object({ from: syncCommitIdSchema.optional() });
+export const syncHeadResponseSchema = z.object({
+    /** `refs/heads/main`, or `null` before the first push: an empty workspace. */
+    head: syncCommitIdSchema.nullable(),
+    /** Commits on `main` in total. */
+    commits: z.number().int().min(0),
+    /** Commits after the request's `from`, when it named one (§3.2). */
+    behind: z.number().int().min(0).optional(),
+    /** The caller's role, so the client refreshes it on every fetch. */
+    role: workspaceRoleSchema,
+    /** The workspace's desktop-activity recording flag, refreshed on every fetch. */
+    recordDesktopActivity: z.boolean().default(false),
+});
+// ---- snapshot ----------------------------------------------------------------------------
+/** `GET …/sync/snapshot?at=`: `at` defaults to the head. */
+export const syncSnapshotQuerySchema = z.object({ at: syncCommitIdSchema.optional() });
+export const syncSnapshotResponseSchema = z.object({
+    head: syncCommitIdSchema.nullable(),
+    files: z.array(syncFileSchema),
+});
+// ---- changes -----------------------------------------------------------------------------
+/** `GET …/sync/changes?from=&to=`: an absent `from` means the empty tree. */
+export const syncChangesQuerySchema = z.object({
+    from: syncCommitIdSchema.optional(),
+    to: syncCommitIdSchema,
+});
+export const syncChangesResponseSchema = z.object({
+    from: syncCommitIdSchema.nullable(),
+    to: syncCommitIdSchema,
+    files: z.array(syncChangeSchema),
+});
+// ---- commits (push) ----------------------------------------------------------------------
+/** One pending commit. The server authors it as the caller; `at` becomes the author date. */
+export const syncPushCommitSchema = z.object({
+    subject: z.string().min(1).max(MAX_SYNC_SUBJECT_LENGTH),
+    /** ISO 8601 with `Z` or an offset (`toISOString()` gives `Z`). It renders as JSON Schema `format: date-time`. */
+    at: z.iso.datetime({ offset: true }),
+    changes: z.array(syncChangeSchema),
+});
+/** `POST …/sync/commits`: `parent` must be the current head (`null` for an empty workspace), or the push is rejected. */
+export const syncPushRequestSchema = z.object({
+    parent: syncCommitIdSchema.nullable(),
+    commits: z.array(syncPushCommitSchema).min(1),
+});
+/** `201`: the new head, and one id per pushed commit, in order. */
+export const syncPushResponseSchema = z.object({
+    head: syncCommitIdSchema,
+    ids: z.array(syncCommitIdSchema),
+});
+// ---- log ---------------------------------------------------------------------------------
+/** `GET …/sync/log?limit=`. Fastify's Ajv coerces the querystring, so the handler reads a number. */
+export const syncLogQuerySchema = z.object({
+    limit: z.number().int().min(1).max(MAX_SYNC_LOG_LIMIT).optional(),
+});
+/**
+ * One commit, newest first. `author` is `Name <email>`. `at` is git's strict ISO author date,
+ * passed on as is: its UTC spelling differs between git versions, so it is not checked as a format.
+ */
+export const syncLogEntrySchema = z.object({
+    id: syncCommitIdSchema,
+    subject: z.string(),
+    author: z.string(),
+    at: z.string(),
+});
+export const syncLogResponseSchema = z.array(syncLogEntrySchema);
+// ---- team secrets (team-secrets spec §5.1) -------------------------------------------------
+/** The most a key request's file may hold, in UTF-8 bytes. */
+export const TEAM_SECRETS_KEY_REQUEST_MAX_BYTES = 4096;
+/**
+ * `POST …/team-secrets/key-requests`: `content` is the key file's text as the app wrote it. The server
+ * derives the path from `keyId` and never parses `content` (plan decision 11).
+ */
+export const teamSecretsKeyRequestSchema = z.object({
+    keyId: z.string().regex(KEY_ID_PATTERN),
+    content: z.string().min(1).max(TEAM_SECRETS_KEY_REQUEST_MAX_BYTES),
+});
+export const teamSecretsKeyRequestResponseSchema = z.object({ head: syncCommitIdSchema });