@antasphere/chassis-server 1.0.2 → 1.2.0

package/src/api/create-api.ts

@@ -7,7 +7,7 @@ import { registerOpenApiDoc } from './index.js';
 import { ulid } from 'ulid';
 import { and, asc, desc, eq } from 'drizzle-orm';
 import { ACTIVE_WORKSPACE_HEADER, type Principal } from '@antasphere/chassis-contract';
-import { instanceRoute, setupRoute } from '@antasphere/chassis-contract/routes';
+import { cliPackageRoute, instanceRoute, setupRoute } from '@antasphere/chassis-contract/routes';
 import {
   account,
   instanceSettings,
@@ -76,11 +76,16 @@ import {
   type WorkspaceCloudDeps
 } from './index.js';
 import { registerSsoConnectRoutes } from './index.js';
+import { registerCliPackageRoutes } from './index.js';
+import { loadCliPackage } from '../cli-package/index.js';
 import { registerSsoLogoutRoutes } from './index.js';
 import { registerMemberRoutes } from './index.js';
 import { demoSessionJudge, demoSignInOn, registerDemoPassRoutes } from './index.js';
 import { registerProjectRoutes } from './index.js';
 import { registerTeamRoutes } from './index.js';
+import { registerWebhookRoutes } from './webhooks.js';
+import type { WebhookService } from '../webhooks/index.js';
+import { bindMembershipRemoval } from '../members/removal.js';
 import { registerApiKeyRoutes } from './index.js';
 import { registerInvitationRoutes } from './index.js';
 import { registerAuditRoutes } from './index.js';
@@ -307,6 +312,8 @@ export interface ApiDeps<
    * the gate compares limits against their oss values and emits nothing.
    */
   entitlementCloud?: EntitlementCloud | undefined;
+  /** The outbound webhooks (PRDCT-3482): the endpoint routes and the catalog. */
+  webhooks: WebhookService;
 }
 
 /** Control-flow marker: the singleton claim lost (instance already set up). */
@@ -357,6 +364,13 @@ export function createApiApp<
   // Demo sign-in (the demo pass spec): DEMO_SIGN_IN on the self-hosted
   // edition only. Off, no demo route, wall or discovery key exists.
   const demoSignIn = demoSignInOn(env, hub, logger);
+  // The tool's own CLI package (PRDCT-3312), read once here. parseEnv has
+  // already refused a CLI_PACKAGE_DIR that does not hold the pair, so a
+  // throw from here (the folder emptied between the two reads) still
+  // refuses the boot, it is never a person's failed install. Served (and
+  // advertised) only where its route is registered: the cloud block below.
+  const cliPackage = loadCliPackage(env.CLI_PACKAGE_DIR);
+  const cliServed = deps.hubSso && deps.hubGrant ? cliPackage : null;
 
   const api = new OpenAPIHono({
     // Validation failures use the same wire shape as every other error.
@@ -573,6 +587,9 @@ export function createApiApp<
   // route itself: oss mounts zero hub surface.
   if (deps.hubSso) {
     api.use('/sso/cli-connect', rateLimit(limiters.cliConnect, clientIp));
+    // The CLI package download (cloud only, api/cli-package.ts) presents the
+    // same one-time hub token at the same cost: the same wall.
+    api.use('/cli/package', rateLimit(limiters.cliConnect, clientIp));
   }
 
   // ── JSON pre-validation in front of the Better Auth mount (AF-1 + the
@@ -832,6 +849,10 @@ export function createApiApp<
         // Present only on a cloud instance whose operator restricted the tool
         // (PRDCT-2947): organizations are opened by Antasphere, not created here.
         ...(hub && env.TOOL_RESTRICTED ? { restricted: true } : {}),
+        // Present only on a cloud instance whose release packed the tool's
+        // CLI (PRDCT-3312): what `POST /cli/package` serves, for the `team`
+        // command to install. An oss boot has no route, so no key either.
+        ...(cliServed ? { cli: { name: cliServed.name, version: cliServed.version } } : {}),
         // What this version declares for the billing rail (§7): the hub seeds
         // from it, staff read it, a client reads the limit it is held to.
         entitlements: {
@@ -1290,6 +1311,14 @@ export function createApiApp<
       cliKeyScopes: tool.scopes.cliKey,
       routes: { ssoCliConnectRoute }
     });
+    // The tool's own CLI package (PRDCT-3312): cloud-only for the same
+    // reason as /sso/cli-connect (it verifies the same hub exchange token
+    // and burns it in the same ledger), so an oss boot leaves the path to
+    // the JSON 404 terminator. Deliberately UNLISTED in the machine scope
+    // allowlist and absent from PUBLIC_API_PATHS: the token rides in the
+    // body, a request without a credential reaches the handler, and an API
+    // key or an OAuth bearer meets 403 endpoint_not_allowed before it.
+    registerCliPackageRoutes(api, { db, hubSso, cliPackage, logger, routes: { cliPackageRoute } });
   }
   // Single logout (SL-2): cloud-only like /sso/cli-connect — an oss boot
   // leaves POST /sso/logout to the JSON 404 terminator. Deliberately
@@ -1309,16 +1338,19 @@ export function createApiApp<
   }
   registerMemberRoutes(api, {
     db,
+    events: chassisRegistry.events,
     auth,
     publicBaseUrl: env.PUBLIC_BASE_URL,
     accountDeletion: deps.accountDeletion,
     hubManaged,
     guestTargetMessage: tool.copy.guestTarget,
-    onMembershipRemoval: tool.membershipRemoval
+    onMembershipRemoval: bindMembershipRemoval(tool.membershipRemoval, { webhooks: deps.webhooks })
   });
   // Teams: the tool's own on self-hosted (and in a cloud-local workspace), the
   // hub's projection in a hub-origin workspace, where the members' gate refuses the writes.
   registerTeamRoutes(api, { db, hubManaged });
+  // Webhooks (PRDCT-3482): the tool's on both editions, never hub-managed (Romain's rule of 27 September 2026).
+  registerWebhookRoutes(api, { service: deps.webhooks });
   if (demoSignIn) {
     registerDemoPassRoutes(api, {
       db,
@@ -1327,7 +1359,13 @@ export function createApiApp<
       guestTargetMessage: tool.copy.guestTarget
     });
   }
-  registerApiKeyRoutes(api, db, apiKeyService, { apiKeysListRoute, apiKeyCreateRoute, apiKeyRevokeRoute });
+  registerApiKeyRoutes(
+    api,
+    db,
+    apiKeyService,
+    { apiKeysListRoute, apiKeyCreateRoute, apiKeyRevokeRoute },
+    chassisRegistry.events
+  );
   registerInvitationRoutes(api, {
     db,
     env,
@@ -1346,7 +1384,7 @@ export function createApiApp<
   // Projects: a subgroup of the workspace with its own members. Deliberately
   // handed NO `hubManaged`: project membership is the tool's own on both
   // editions, picked among the workspace's existing members.
-  registerProjectRoutes(api, { db });
+  registerProjectRoutes(api, { db, webhooks: deps.webhooks });
   registerAuditRoutes(api, db);
   registerExportRoutes(api, {
     db,

package/src/api/index.ts

@@ -2,6 +2,7 @@ export { registerApiKeyRoutes } from './apikeys.js';
 export { registerAuditRoutes } from './audit.js';
 export { registerBreakGlassRoutes } from './break-glass.js';
 export { registerCliAuthRoutes } from './cli-auth.js';
+export { registerCliPackageRoutes, type CliPackageRouteDeps } from './cli-package.js';
 export { demoSessionJudge, demoSignInOn, registerDemoPassRoutes } from './demo-passes.js';
 export {
   registerExportRoutes,

package/src/api/invitations.ts

@@ -380,6 +380,12 @@ export function registerInvitationRoutes(api: OpenAPIHono, deps: InvitationRoute
       invitationId: invitation.id,
       userId
     });
+    // The person is a member now (the webhooks' `member.joined` rides the bus).
+    registry.events.emit('member.joined', {
+      workspaceId: invitation.workspaceId,
+      userId,
+      role: invitation.role
+    });
     // Public endpoint: no principal in context, write the audit row directly.
     await audit.write({
       workspaceId: invitation.workspaceId,

package/src/api/members.ts

@@ -20,12 +20,15 @@ import { hubManagedMembershipGate } from '../middleware/hub-managed.js';
 import {
   deleteMembershipGrants,
   mergeRemovalCounts,
-  type MembershipRemovalHook,
+  type BoundMembershipRemoval,
   type RemovalCounts
 } from '../members/removal.js';
+import type { EventBus } from '../platform/events.js';
 
 export interface MemberRouteDeps {
   db: Db;
+  /** The bus, for `member.removed` after a removal commits (the webhooks bridge it). */
+  events?: EventBus | undefined;
   auth: Auth;
   publicBaseUrl: string;
   accountDeletion: AccountDeletionService;
@@ -38,7 +41,7 @@ export interface MemberRouteDeps {
   /** The tool's `guest_target` sentence (`copy.guestTarget`). */
   guestTargetMessage: string;
   /** The tool's half of a removal (the `membershipRemoval` slot), run in the removal's transaction. */
-  onMembershipRemoval?: MembershipRemovalHook | undefined;
+  onMembershipRemoval?: BoundMembershipRemoval | undefined;
 }
 
 const err = (code: string, message: string) => ({ error: { code, message } });
@@ -425,6 +428,7 @@ export function registerMemberRoutes(api: OpenAPIHono, deps: MemberRouteDeps): v
       .where(eq(workspaceMembers.id, target.id))
       .limit(1);
 
+    deps.events?.emit('member.removed', { workspaceId: principal.workspaceId, userId: target.userId });
     c.set('audit', {
       action: 'member.remove',
       resourceType: 'member',

package/src/api/projects.ts

@@ -1,4 +1,5 @@
 import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { WebhookEmitter } from '../webhooks/service.js';
 import type { Context } from 'hono';
 import { and, desc, eq, isNotNull, isNull, sql } from 'drizzle-orm';
 import { projectRoleAtLeast, type Principal, type ProjectRole } from '@antasphere/chassis-contract';
@@ -62,6 +63,8 @@ import {
  */
 export interface ProjectRouteDeps {
   db: Db;
+  /** The outbound webhooks' emitter (PRDCT-3482): `project.created` inside the create's transaction, `project.archived` after the archive. */
+  webhooks: WebhookEmitter;
 }
 
 const err = (code: string, message: string) => ({ error: { code, message } });
@@ -210,7 +213,7 @@ interface MemberUnionRow {
 }
 
 export function registerProjectRoutes(api: OpenAPIHono, deps: ProjectRouteDeps): void {
-  const { db } = deps;
+  const { db, webhooks } = deps;
 
   // Projects are a workspace-level surface: a guest membership exists for
   // principal resolution only (D2) and is refused the whole subtree, flat, on
@@ -362,6 +365,12 @@ export function registerProjectRoutes(api: OpenAPIHono, deps: ProjectRouteDeps):
         role: 'manager',
         addedBy: principal.userId
       });
+      await webhooks.emit(tx, {
+        workspaceId: principal.workspaceId,
+        type: 'project.created',
+        subjects: { project: project!.id },
+        data: { projectId: project!.id, name: body.name, createdBy: principal.userId }
+      });
       return readProject(tx, principal, project!.id);
     });
     // The principal resolved from an active membership a moment ago; losing
@@ -435,6 +444,12 @@ export function registerProjectRoutes(api: OpenAPIHono, deps: ProjectRouteDeps):
       .returning({ id: projects.id });
     if (updated.length === 0) return c.json(archived(), 409);
     const project = (await readProject(db, principal, id))!;
+    await webhooks.emit(db, {
+      workspaceId: principal.workspaceId,
+      type: 'project.archived',
+      subjects: { project: id },
+      data: { projectId: id, name: project.name }
+    });
     c.set('audit', { action: 'project.archive', resourceType: 'project', resourceId: id });
     return c.json(toWire(project), 200);
   });

package/src/api/webhooks.ts

@@ -0,0 +1,205 @@
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { Principal } from '@antasphere/chassis-contract';
+import {
+  webhookCatalogRoute,
+  webhookCreateRoute,
+  webhookDeleteRoute,
+  webhookDeliveriesListRoute,
+  webhookDeliveryGetRoute,
+  webhookGetRoute,
+  webhookRedeliverRoute,
+  webhookRotateSecretRoute,
+  webhooksListRoute,
+  webhookTestRoute,
+  webhookUpdateRoute
+} from '@antasphere/chassis-contract/routes';
+import { requireAuth, requireNonGuest } from '../middleware/auth-context.js';
+import { catalogToWire, WebhookRefusedError, type WebhookService } from '../webhooks/index.js';
+
+/**
+ * The webhook routes (PRDCT-3482), the same on both editions and never
+ * hub-managed: a webhook is the tool's, on a self-hosted instance and on
+ * the cloud alike (Romain's rule of 27 September 2026).
+ *
+ * A webhook is a standing read of the workspace to a URL of the caller's
+ * choice, so the whole family, reads included, is an OWNER's or an ADMIN's
+ * act, checked inside each handler (never a path-pattern `requireRole`, the
+ * `/thing/:id` trap: the catalog lives under the same prefix and is every
+ * non-guest member's). A guest is refused flat; a session a demo link
+ * opened is refused every write (`DEMO_SESSION_REFUSED_API_ROUTES`); a
+ * machine principal needs the tool's dedicated scope (`middleware/scopes.ts`).
+ * An endpoint of another workspace reads as absent: 404, never 403.
+ *
+ * The secret is answered ONCE, at creation and at rotation, and never
+ * written to the audit row.
+ */
+export interface WebhookRouteDeps {
+  service: WebhookService;
+}
+
+const err = (code: string, message: string) => ({ error: { code, message } });
+const FORBIDDEN = err('forbidden', 'Only an owner or an admin manages webhooks');
+const NOT_FOUND = err('not_found', 'Webhook not found');
+const DELIVERY_NOT_FOUND = err('not_found', 'Delivery not found');
+
+const canManage = (principal: Principal) => principal.role === 'owner' || principal.role === 'admin';
+
+export function registerWebhookRoutes(api: OpenAPIHono, deps: WebhookRouteDeps): void {
+  const { service } = deps;
+
+  for (const path of ['/webhooks', '/webhooks/*']) {
+    api.use(path, requireAuth());
+    api.use(path, requireNonGuest());
+  }
+
+  // The catalog BEFORE the `{id}` routes: `events` is not an id. Every
+  // non-guest member reads it (an agent discovers the types with a read key).
+  api.openapi(webhookCatalogRoute, async (c) => c.json(catalogToWire(service.catalog), 200));
+
+  api.openapi(webhooksListRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { cursor, limit } = c.req.valid('query');
+    return c.json(await service.list(principal.workspaceId, cursor, limit), 200);
+  });
+
+  api.openapi(webhookCreateRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const body = c.req.valid('json');
+    let created: Awaited<ReturnType<WebhookService['create']>>;
+    try {
+      created = await service.create(principal.workspaceId, principal.userId, body);
+    } catch (e) {
+      if (e instanceof WebhookRefusedError && e.code !== 'not_found')
+        return c.json(err(e.code, e.message), 400);
+      throw e;
+    }
+    c.set('audit', {
+      action: 'webhook.create',
+      resourceType: 'webhook',
+      resourceId: created.endpoint.id,
+      metadata: {
+        url: created.endpoint.url,
+        events: created.endpoint.events,
+        filters: created.endpoint.filters
+      }
+    });
+    return c.json({ ...created.endpoint, secret: created.secret }, 201);
+  });
+
+  api.openapi(webhookGetRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const endpoint = await service.get(principal.workspaceId, id);
+    return endpoint ? c.json(endpoint, 200) : c.json(NOT_FOUND, 404);
+  });
+
+  api.openapi(webhookUpdateRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const body = c.req.valid('json');
+    let updated: Awaited<ReturnType<WebhookService['update']>>;
+    try {
+      updated = await service.update(principal.workspaceId, id, body);
+    } catch (e) {
+      if (e instanceof WebhookRefusedError && e.code !== 'not_found')
+        return c.json(err(e.code, e.message), 400);
+      throw e;
+    }
+    if (!updated) return c.json(NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.update',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { fields: Object.keys(body) }
+    });
+    return c.json(updated, 200);
+  });
+
+  api.openapi(webhookDeleteRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const removed = await service.remove(principal.workspaceId, id);
+    if (!removed) return c.json(NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.delete',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { url: removed.url }
+    });
+    return c.json(removed, 200);
+  });
+
+  api.openapi(webhookRotateSecretRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const rotated = await service.rotateSecret(principal.workspaceId, id);
+    if (!rotated) return c.json(NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.rotate_secret',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { previousSecretExpiresAt: rotated.previousSecretExpiresAt }
+    });
+    return c.json(
+      {
+        ...rotated.endpoint,
+        secret: rotated.secret,
+        previousSecretExpiresAt: rotated.previousSecretExpiresAt
+      },
+      200
+    );
+  });
+
+  api.openapi(webhookTestRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const delivery = await service.test(principal.workspaceId, id, principal.userId);
+    if (!delivery) return c.json(NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.test',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { deliveryId: delivery.id, status: delivery.status, lastStatusCode: delivery.lastStatusCode }
+    });
+    return c.json({ delivery }, 200);
+  });
+
+  api.openapi(webhookDeliveriesListRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const { cursor, limit, status } = c.req.valid('query');
+    const page = await service.listDeliveries(principal.workspaceId, id, { cursor, limit, status });
+    return page ? c.json(page, 200) : c.json(NOT_FOUND, 404);
+  });
+
+  api.openapi(webhookDeliveryGetRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id, deliveryId } = c.req.valid('param');
+    const delivery = await service.getDelivery(principal.workspaceId, id, deliveryId);
+    return delivery ? c.json(delivery, 200) : c.json(DELIVERY_NOT_FOUND, 404);
+  });
+
+  api.openapi(webhookRedeliverRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id, deliveryId } = c.req.valid('param');
+    const delivery = await service.redeliver(principal.workspaceId, id, deliveryId);
+    if (!delivery) return c.json(DELIVERY_NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.redeliver',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { deliveryId: delivery.id, eventId: delivery.eventId, eventType: delivery.eventType }
+    });
+    return c.json(delivery, 201);
+  });
+}

package/src/boot.ts

@@ -52,6 +52,8 @@ import { createOtel } from './observability/index.js';
 import { bindEditionSeams } from './platform/index.js';
 import { AllowAllEntitlements } from './platform/index.js';
 import { EventBus } from './platform/index.js';
+import { buildWebhookCatalog, WebhookService, webhookJobs } from './webhooks/index.js';
+import { bindMembershipRemoval } from './members/removal.js';
 import { LocalIdentityProvider } from './platform/index.js';
 import { createRegistry } from './platform/index.js';
 import { NoopUsageSink } from './platform/index.js';
@@ -540,6 +542,26 @@ export async function bootPlatform<
     }
   }
 
+  // Outbound webhooks (PRDCT-3482): the catalog checked, the service built
+  // BEFORE the job runtime (its four queues are declared to it like a tool's
+  // own) and attached to it right after; a tool's `services` slot receives
+  // the emitter, the API app the service, the bus the chassis's own events.
+  const webhookCatalog = buildWebhookCatalog(tool.webhooks);
+  const webhooks = new WebhookService({
+    db: db.db,
+    logger,
+    authSecret,
+    identity: tool.identity,
+    version: tool.runtime.version,
+    policy: { allowPrivateNetworks: env.WEBHOOKS_ALLOW_PRIVATE_NETWORKS, httpsOnly: env.EDITION === 'cloud' },
+    email,
+    brand: { name: tool.identity.displayName, tagline: tool.copy.mail.tagline },
+    publicBaseUrl: env.PUBLIC_BASE_URL,
+    catalog: webhookCatalog,
+    dials: overrides.webhookDials,
+    fetchOptions: overrides.webhookFetch
+  });
+
   // The live user-scoped federation stack (cloud only, internal/federation.md):
   // each user's OWN hub grant (offline_access refresh token on the account
   // row) → as-the-user `GET /orgs` reads → the org reconciler that the
@@ -611,7 +633,7 @@ export async function bootPlatform<
           audit,
           logger,
           dials: hubDials,
-          onMembershipRemoval: tool.membershipRemoval,
+          onMembershipRemoval: bindMembershipRemoval(tool.membershipRemoval, { webhooks }),
           ...(overrides.hubNow ? { now: overrides.hubNow } : {})
         })
       : undefined;
@@ -662,9 +684,14 @@ export async function bootPlatform<
     overrides.usageDownstream ?? hubUsagePoster ?? new NoopUsageSink(),
     auth,
     audit,
-    tool.jobs?.({ env, db: db.db, logger, getTool: () => domainRef.current }) ?? [],
+    [
+      ...webhookJobs(webhooks, logger, env.WEBHOOK_DELIVERY_RETENTION_DAYS),
+      ...(tool.jobs?.({ env, db: db.db, logger, getTool: () => domainRef.current }) ?? [])
+    ],
     usageRetry
   );
+  webhooks.attach(jobs.boss);
+  webhooks.bindBus(events.chassisView());
   // The tool's billing-rail declarations (slot 22), asserted once here: a
   // route that meters an action the price book does not know, or a limit no
   // tier values, stops the boot naming the route.
@@ -806,6 +833,7 @@ export async function bootPlatform<
     events,
     authSecret,
     timers: jobs.timers,
+    webhooks,
     overrides: overrides.tool
   };
   const domain = tool.services(serviceCore);
@@ -849,6 +877,7 @@ export async function bootPlatform<
     principalGate: seams.principalGate,
     entitlements,
     entitlementCloud,
+    webhooks,
     // Cloud only (PRDCT-2443): POST /workspaces creates the organization at
     // the hub AS THE CALLER, then forces their reconcile. undefined on oss —
     // the route creates locally there.
@@ -885,7 +914,8 @@ export async function bootPlatform<
     ...(hubGrant?.promMetrics ?? []),
     ...(hubUsagePoster?.promMetrics ?? []),
     ...(hubCreditCheck?.promMetrics ?? []),
-    ...jobs.promMetrics
+    ...jobs.promMetrics,
+    ...webhooks.promMetrics
   ]) {
     metrics.registry.registerMetric(metric);
   }
@@ -952,5 +982,19 @@ export async function bootPlatform<
     state.reason = readinessRefusal;
   }
 
-  return { app, env, logger, state, db, auth, registry, jobs, email, otel, authSecret, tool: domain };
+  return {
+    app,
+    env,
+    logger,
+    state,
+    db,
+    auth,
+    registry,
+    jobs,
+    email,
+    otel,
+    authSecret,
+    webhooks,
+    tool: domain
+  };
 }

package/src/cli-package/index.ts

@@ -0,0 +1,88 @@
+import { readFileSync, statSync, type Stats } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The tool's own CLI package, as the release packed it (PRDCT-3312): the
+ * folder `CLI_PACKAGE_DIR` names holds `package.tgz` (the output of
+ * `pnpm pack` of the tool's `packages/cli`) beside a copy of that package's
+ * `package.json`. The instance reads the pair ONCE at boot and serves the
+ * tarball on `POST /cli/package` (api/cli-package.ts, cloud only) to a member
+ * the hub let into the tool; discovery advertises `cli { name, version }` so
+ * the `team` command knows what it installs and whether to update.
+ *
+ * A folder that is named but does not hold the pair, or whose `package.json`
+ * carries no string `name` and `version`, refuses the boot (env.ts): a
+ * misconfiguration is proven at the image, never discovered by a person's
+ * install. Pure: nothing runs at import; the reads are synchronous and happen
+ * when the boot asks.
+ */
+export interface CliPackage {
+  /** The package's npm name, from its `package.json` (e.g. `@scope/tool`). */
+  name: string;
+  /** The package's version, from its `package.json`. */
+  version: string;
+  /** The tarball's path (the configured folder joined with `package.tgz`), what the route streams. */
+  path: string;
+  /** The tarball's size when the boot read it (the route stats the file again when it serves). */
+  sizeBytes: number;
+  /** npm's own pack name for the pair, the attachment's filename. */
+  filename: string;
+}
+
+/** The tarball's name inside the folder, whatever the package is called. */
+export const CLI_PACKAGE_TARBALL = 'package.tgz';
+/** The manifest copy beside it. */
+export const CLI_PACKAGE_MANIFEST = 'package.json';
+
+/**
+ * npm's own pack filename: the scope's `@` dropped and its `/` turned into
+ * `-` (`@scope/tool` + `1.2.3` → `scope-tool-1.2.3.tgz`); an unscoped name is
+ * kept as it is (`tool` → `tool-1.2.3.tgz`).
+ */
+export function packFilename(name: string, version: string): string {
+  const base = name.startsWith('@') ? name.slice(1).replace('/', '-') : name;
+  return `${base}-${version}.tgz`;
+}
+
+/**
+ * Read the folder `CLI_PACKAGE_DIR` names. `undefined` (the variable unset)
+ * answers null: the instance serves no CLI. A named folder answers the
+ * package, or THROWS an Error naming the folder and the missing piece.
+ */
+export function loadCliPackage(dir: string | undefined): CliPackage | null {
+  if (dir === undefined) return null;
+  const refuse = (what: string): never => {
+    throw new Error(`CLI_PACKAGE_DIR=${dir}: ${what}`);
+  };
+
+  const tarball = join(dir, CLI_PACKAGE_TARBALL);
+  let stat: Stats;
+  try {
+    stat = statSync(tarball);
+  } catch {
+    return refuse(`no ${CLI_PACKAGE_TARBALL} in the folder (the output of \`pnpm pack\` of the CLI package)`);
+  }
+  if (!stat.isFile()) return refuse(`${CLI_PACKAGE_TARBALL} is not a file`);
+
+  let raw: string;
+  try {
+    raw = readFileSync(join(dir, CLI_PACKAGE_MANIFEST), 'utf8');
+  } catch {
+    return refuse(`no ${CLI_PACKAGE_MANIFEST} in the folder (a copy of the CLI package's manifest)`);
+  }
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(raw);
+  } catch {
+    return refuse(`${CLI_PACKAGE_MANIFEST} is not valid JSON`);
+  }
+  const { name, version } = (manifest ?? {}) as { name?: unknown; version?: unknown };
+  if (typeof name !== 'string' || name.length === 0) {
+    return refuse(`${CLI_PACKAGE_MANIFEST} carries no string "name"`);
+  }
+  if (typeof version !== 'string' || version.length === 0) {
+    return refuse(`${CLI_PACKAGE_MANIFEST} carries no string "version"`);
+  }
+
+  return { name, version, path: tarball, sizeBytes: stat.size, filename: packFilename(name, version) };
+}

package/src/email/index.ts

@@ -24,3 +24,4 @@ export {
   buildPasswordResetEmail,
   buildVerifyEmailEmail
 } from './templates.js';
+export { buildWebhookDisabledEmail, type WebhookDisabledEmailParams } from '../webhooks/mail.js';