@boxxy/server 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/server</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/server"><img src="https://img.shields.io/npm/v/@boxxy/server" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+The boxxy server: the API on its owner and worker listeners, and the runner tick that claims tasks,
+reads sessions and sends the facts to pepys.
+
+`startServer({ env, log })` reads the configuration file at `BOXXY_CONFIG`, the trust documents and
+the tokens from the environment, then starts both listeners, the tick, the pull request watch and
+the outbox sender. It answers `refused` with a message that names each missing variable and never a
+secret value.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/server) with Bun:
+
+```bash
+bun add @boxxy/server
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Usage
+
+Set the configuration path and the tokens, then start the server from the package folder:
+
+```bash
+BOXXY_CONFIG=/etc/boxxy/boxxy.json \
+BOXXY_WORKER_TOKEN=<worker_token> \
+BOXXY_ATC_TOKEN=<atc_token> \
+bun run start
+```
+
+- `<worker_token>` is the token the broker sends on every request to the worker listener.
+- `<atc_token>` is the token the server sends to the atc daemon.
+
+With a `pepys` section in the configuration, also set `BOXXY_PEPYS_SIGNING_SECRET`. With a `github`
+section, set `BOXXY_GITHUB_TOKEN` unless a broker adds the GitHub credential.
+
+## Features
+
+- `startServer`, which wires the store, the atc worker and notifier, pepys and both listeners.
+- `serveApi`, the two listeners as Elysia apps, for a caller that builds its own dependencies.
+- `serverConfigSchema`, the configuration file's schema.
+- `./test-utils/create-test-server`, the API on in-memory fakes, for tests.
+
+## Documentation
+
+[The API and its auth](../../docs/design/boxxy/v1-api-and-auth.md) sets out the listeners, the
+tokens and which caller may call each procedure.

package/dist/auth/authorize-call.d.ts

@@ -0,0 +1,11 @@
+import type { ProvenCall, RequestContext } from '../types.ts';
+export type CallAuthorization = {
+    readonly kind: 'owner';
+} | {
+    readonly kind: 'session';
+    readonly call: ProvenCall | null;
+} | {
+    readonly kind: 'refused';
+    readonly code: 'UNAUTHORIZED' | 'FORBIDDEN';
+};
+export declare function authorizeCall(ctx: RequestContext, path: readonly string[]): Promise<CallAuthorization>;

package/dist/auth/is-browser-request.d.ts

@@ -0,0 +1 @@
+export declare function isBrowserRequest(headers: Headers): boolean;

package/dist/auth/pick-request-scope.d.ts

@@ -0,0 +1,9 @@
+import type { Listener, RequestScope } from '../types.ts';
+interface ScopeInput {
+    readonly listener: Listener;
+    readonly authorization: string | null;
+    readonly workerTokenDigest: Uint8Array;
+}
+export declare function pickRequestScope(input: ScopeInput): RequestScope | null;
+export declare function buildTokenDigest(token: string): Uint8Array;
+export {};

package/dist/config/pick-server-secrets.d.ts

@@ -0,0 +1,16 @@
+import type { ServerConfig } from './server-config-schema.ts';
+interface ServerSecrets {
+    readonly workerToken: string;
+    readonly atcToken: string;
+    readonly pepysSigningSecret: string | null;
+    readonly githubToken: string | null;
+}
+export type SecretsAnswer = {
+    readonly kind: 'found';
+    readonly secrets: ServerSecrets;
+} | {
+    readonly kind: 'missing';
+    readonly names: readonly string[];
+};
+export declare function pickServerSecrets(config: ServerConfig, env: Readonly<Record<string, string | undefined>>): SecretsAnswer;
+export {};

package/dist/config/read-caller-proof.d.ts

@@ -0,0 +1,10 @@
+import type { CallerProof, Clock } from '@boxxy/model';
+import type { ServerConfig } from './server-config-schema.ts';
+export type ProofAnswer = {
+    readonly kind: 'read';
+    readonly callerProof: CallerProof;
+} | {
+    readonly kind: 'refused';
+    readonly message: string;
+};
+export declare function readCallerProof(trustedIssuers: ServerConfig['trustedIssuers'], clock: Clock): Promise<ProofAnswer>;

package/dist/config/read-server-config.d.ts

@@ -0,0 +1,9 @@
+import type { ServerConfig } from './server-config-schema.ts';
+export type ConfigAnswer = {
+    readonly kind: 'read';
+    readonly config: ServerConfig;
+} | {
+    readonly kind: 'invalid';
+    readonly message: string;
+};
+export declare function readServerConfig(path: string): Promise<ConfigAnswer>;

package/dist/config/read-trusted-issuers.d.ts

@@ -0,0 +1,8 @@
+export type IssuersAnswer = {
+    readonly kind: 'read';
+    readonly issuers: readonly unknown[];
+} | {
+    readonly kind: 'invalid';
+    readonly message: string;
+};
+export declare function readTrustedIssuers(folders: readonly string[]): Promise<IssuersAnswer>;

package/dist/config/server-config-schema.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare const serverConfigSchema: z.ZodObject<{
+    runner: z.ZodString;
+    store: z.ZodObject<{
+        file: z.ZodString;
+    }, z.core.$strict>;
+    rules: z.ZodObject<{
+        folder: z.ZodString;
+    }, z.core.$strict>;
+    api: z.ZodObject<{
+        listen: z.ZodObject<{
+            hostname: z.ZodString;
+            port: z.ZodInt;
+        }, z.core.$strict>;
+        workerListen: z.ZodObject<{
+            hostname: z.ZodString;
+            port: z.ZodInt;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    spawn: z.ZodObject<{
+        target: z.ZodString;
+        repoPaths: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>;
+    atc: z.ZodObject<{
+        url: z.ZodURL;
+        trustedFolders: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+        noticeSession: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    trustedIssuers: z.ZodOptional<z.ZodObject<{
+        folders: z.ZodArray<z.ZodString>;
+        audience: z.ZodString;
+    }, z.core.$strict>>;
+    pepys: z.ZodOptional<z.ZodObject<{
+        ingestUrl: z.ZodURL;
+        apiUrl: z.ZodURL;
+        environment: z.ZodString;
+    }, z.core.$strict>>;
+    github: z.ZodOptional<z.ZodObject<{
+        baseUrl: z.ZodURL;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ServerConfig = z.infer<typeof serverConfigSchema>;

package/dist/create-capacity-backoff.d.ts

@@ -0,0 +1,2 @@
+import type { CapacityBackoff } from '@boxxy/model';
+export declare function createCapacityBackoff(): CapacityBackoff;