@fugood/buttress-server 2.24.2 → 2.25.0-beta.11

package/README.md

@@ -20,6 +20,84 @@ npx bricks-buttress --config ./config.toml
 npx bricks-buttress
 ```
 
+## Workspace Binding (`bricks buttress`)
+
+By default, a buttress-server runs in **public mode**: any client on the LAN can connect, no auth required. To restrict access to a single BRICKS workspace and enable workspace-scoped JWT auth, **bind** the server with the `bricks buttress` CLI commands. Once bound, the server only accepts WebSocket / file-transfer requests carrying a valid access token signed by that workspace's issuer.
+
+The `bricks` CLI is the tool that performs the binding and writes the local state file. Install it first — see the [bricks-cli docs](https://docs.bricks.tools/cli) — then `bricks auth login` with the workspace owner's account before running the commands below.
+
+### Bind a server to a workspace
+
+```bash
+# Pair the local machine's buttress-server with the workspace of the current bricks-cli profile
+bricks buttress bind
+
+# Override the auto-detected server id, give it a friendly name, or write to a custom state dir
+bricks buttress bind --server-id buttress-mac-studio --name "Studio LLM" --state-dir /etc/buttress
+
+# For headless/remote setups: emit state.json to stdout instead of writing to disk
+bricks buttress bind --print > /etc/buttress/state.json
+```
+
+The state file (`~/.bricks-cli/buttress/state.json` by default, or `$BRICKS_BUTTRESS_STATE_DIR`) stores:
+
+- `workspace.id` / `workspace.name` — which workspace this server belongs to
+- `workspace.serverId` — the server's stable id (defaults to `buttress-<machineId>`)
+- `workspace.issuerPublicKey` + `workspace.kid` — Ed25519 SPKI used to verify access tokens
+
+**Restart `bricks-buttress` after binding** for the change to take effect — the state file is read once at startup.
+
+### Inspect bindings
+
+```bash
+# Show local state.json + the workspace-side bound list
+bricks buttress status
+
+# Same, JSON-formatted
+bricks buttress status --json
+```
+
+### Discover servers on the LAN
+
+```bash
+# UDP scan + HTTP /buttress/info verification (3s timeout by default)
+bricks buttress scan
+
+# UDP only (skip the /buttress/info round-trip)
+bricks buttress scan --udp-only
+
+# Machine-readable
+bricks buttress scan --json
+```
+
+`scan` lists every buttress-server visible on the LAN, including unbound (public) ones, with their version, auth state (`open` vs `JWT required` + kid), bound workspace, and per-generator hardware caps (`score`, GPU, usable memory). Servers whose workspace matches your current `bricks-cli` profile are highlighted; this is purely a discovery command and does not mint any tokens.
+
+### Unbind
+
+```bash
+# Remove the binding from the workspace and delete the local state.json
+bricks buttress unbind
+
+# Keep the local state file (useful if you only want to revoke server-side)
+bricks buttress unbind --keep-local
+```
+
+After unbinding, restart the server to return it to public mode.
+
+### Issue a long-lived access token
+
+For headless callers (CI, ctor agents) that already hold a workspace token, mint a long-lived buttress access token instead of relying on a per-launcher session token:
+
+```bash
+# Default 30-day TTL
+bricks buttress issue-token
+
+# Custom TTL (seconds), JSON output for scripting
+bricks buttress issue-token --ttl 3600 --json
+```
+
+The token claims `{ k: 'ba', w_id, st: 'ws', sid, jti, exp }` and any buttress-server bound to the same workspace will accept it.
+
 ## Configuration
 
 Configuration can be provided via:
@@ -157,6 +235,25 @@ Examples:
   bricks-buttress --test-caps ggml-stt --test-caps-model-id BricksDisplay/whisper-ggml:ggml-small.bin
 ```
 
+## Compatibility Endpoints (Experimental)
+
+The server can expose OpenAI- and Anthropic-compatible HTTP endpoints in addition to the native RPC. Each endpoint is opt-in via the TOML config:
+
+```toml
+[openai_compat]
+enabled = true
+# cors_allowed_origins = "*"          # Or a list of origins; defaults to disabled
+
+[anthropic_messages]
+enabled = true
+# cors_allowed_origins = ["http://localhost:3000"]
+```
+
+| Endpoint              | Config flag                          |
+| --------------------- | ------------------------------------ |
+| `/oai-compat/v1/*`    | `[openai_compat] enabled = true`     |
+| `/anthropic-messages` | `[anthropic_messages] enabled = true` |
+
 ## Session State Cache
 
 The server supports session state caching for ggml-llm generators, which saves KV cache state to disk after completions. This enables:

package/config/sample.toml

@@ -11,15 +11,24 @@
 # HF_TOKEN = "your_huggingface_token_here"
 # CUDA_VISIBLE_DEVICES = "0"
 
+[autodiscover]
+enabled = true
+
 [server]
 port = 2080
 log_level = "info"
 # max_body_size = "100MB"  # Supports string (e.g., "100MB", "1GB") or number in bytes
 
 [openai_compat]
+enabled = true
 # cors_allowed_origins = ["http://localhost:3000", "https://example.com"]  # Restrict to specific origins
 # cors_allowed_origins = "*"  # Allow all origins (default)
 
+[anthropic_messages]
+enabled = true
+# cors_allowed_origins = ["http://localhost:3000", "https://example.com"]
+# cors_allowed_origins = "*"
+
 [runtime]
 cache_dir = "./.buttress-cache"
 # huggingface_token = "hf_xx"

package/lib/index.d.mts

@@ -1,5 +1,6 @@
 
 import { AnyElysia, Elysia } from "elysia";
+import crypto from "node:crypto";
 import { ReadableStream } from "node:stream/web";
 import { EventEmitter } from "node:events";
 
@@ -229,9 +230,11 @@ type GeneratorConfig = {
 type GlobalConfig = {
   runtime?: RuntimeConfig;
   openai_compat?: {
+    enabled?: boolean;
     cors_allowed_origins?: string | string[];
   };
   anthropic_messages?: {
+    enabled?: boolean;
     cors_allowed_origins?: string | string[];
   };
 } & Record<string, any>;
@@ -277,24 +280,40 @@ type Config = {
   generators: GeneratorConfig[];
 };
 type GeneratorInfo = {
-  type: GeneratorType;
+  type: GeneratorType; /** Performance score 0–100 from buttress-hardware-guardrails. */
+  score?: number; /** Whether the host has an accelerator (GPU/Metal/etc) for this backend. */
+  hasGpu?: boolean; /** Usable memory in bytes for this backend (GPU when present, else CPU). */
+  usableBytes?: number;
 } & Record<string, any>;
 type ServerInfo = {
   id: string;
   name: string;
+  version: string;
   address: string;
   port: number;
   url: string;
   generators: GeneratorInfo[];
   authentication: {
     required: boolean;
-    type: string;
+    type: string; /** Issuer key id (when type === 'workspace-jwt'). */
+    kid?: string; /** True when buttress is paired with a workspace. */
+    bound?: boolean;
+  }; /** Workspace identity (only present when paired). */
+  workspace?: {
+    id: string;
+    name?: string;
   };
 };
 //#endregion
 //#region src/autodiscover/types.d.ts
 type GetServerInfoFn = () => ServerInfo;
 //#endregion
+//#region src/autodiscover/udp.d.ts
+interface AnnounceSigner {
+  kid: string;
+  privateKey: crypto.KeyObject;
+}
+//#endregion
 //#region src/autodiscover/index.d.ts
 /**
  * Autodiscover service that manages discovery transports.
@@ -304,9 +323,10 @@ type GetServerInfoFn = () => ServerInfo;
 declare class AutodiscoverService {
   private config;
   private getServerInfo;
+  private signer;
   private transports;
   private started;
-  constructor(config: AutodiscoverConfig, getServerInfo: GetServerInfoFn);
+  constructor(config: AutodiscoverConfig, getServerInfo: GetServerInfoFn, signer: AnnounceSigner | null);
   start(): Promise<void>;
   stop(): Promise<void>;
 }