@antasphere/chassis-server 1.0.0

package/src/secret.ts

@@ -0,0 +1,115 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Logger } from './logger.js';
+
+/**
+ * Resolve the auth secret: prefer AUTH_SECRET from the environment; otherwise
+ * persist a generated one under DATA_DIR (n8n-style zero-config first run).
+ * The file is written 0600 and reused on every subsequent boot, so sessions
+ * survive restarts even when the operator never set a secret.
+ */
+export async function resolveAuthSecret(
+  envSecret: string | undefined,
+  dataDir: string,
+  log: Logger
+): Promise<string> {
+  if (envSecret) return envSecret;
+
+  const secretPath = join(dataDir, 'secret');
+  try {
+    const existing = (await readFile(secretPath, 'utf8')).trim();
+    if (existing.length >= 32) return existing;
+    log.warn({ secretPath }, 'existing secret file is too short — regenerating');
+  } catch {
+    // no secret file yet
+  }
+
+  const secret = randomBytes(32).toString('hex');
+  await mkdir(dataDir, { recursive: true });
+  // Write + rename (same dir → atomic) so a crash mid-write never leaves a
+  // truncated secret that a later boot would accept and lock everyone out.
+  const tmpPath = join(dataDir, `.secret.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    await writeFile(tmpPath, secret + '\n', { mode: 0o600 });
+    await rename(tmpPath, secretPath);
+  } catch (err) {
+    await rm(tmpPath, { force: true });
+    throw err;
+  }
+  log.warn(
+    { secretPath },
+    'AUTH_SECRET was not set — generated one into the data volume. ' +
+      'Set AUTH_SECRET explicitly for multi-replica deployments; all replicas must share it.'
+  );
+  return secret;
+}
+
+/** Where a boot-generated setup token lives until the instance is claimed. */
+export function generatedSetupTokenPath(dataDir: string): string {
+  return join(dataDir, 'setup-token');
+}
+
+/**
+ * The credential POST /api/v1/setup REQUIRES (PRDCT-1347, audit A7). The
+ * first-boot claim decides who owns the instance, so it can never be free:
+ *
+ *  - `SETUP_TOKEN` set → that is the token (setup.sh writes one);
+ *  - instance already set up → nothing to claim, no token needed (null);
+ *  - otherwise → a token is generated ONCE into `$DATA_DIR/setup-token`
+ *    (0600, atomic write, reused on every later boot until the claim) and
+ *    printed to the container log, so the `docker run` / plain
+ *    `docker compose up` paths — which never go through setup.sh — still
+ *    produce an instance claimable only with a secret. The file is removed
+ *    once setup completes (see clearGeneratedSetupToken).
+ *
+ * Optional-when-set was the hole: a minimal-env container answered the
+ * claim with 201 and no credential at all.
+ */
+export async function resolveSetupToken(
+  envToken: string | undefined,
+  dataDir: string,
+  alreadySetUp: boolean,
+  log: Logger
+): Promise<string | null> {
+  if (envToken) return envToken;
+  if (alreadySetUp) return null;
+
+  const tokenPath = generatedSetupTokenPath(dataDir);
+  try {
+    const existing = (await readFile(tokenPath, 'utf8')).trim();
+    if (existing.length >= 16) {
+      log.warn(
+        { tokenPath },
+        `SETUP_TOKEN is not set — the setup wizard requires the token generated at first boot: ${existing}`
+      );
+      return existing;
+    }
+    log.warn({ tokenPath }, 'existing setup-token file is too short — regenerating');
+  } catch {
+    // no token file yet
+  }
+
+  const token = randomBytes(16).toString('hex');
+  await mkdir(dataDir, { recursive: true });
+  const tmpPath = join(dataDir, `.setup-token.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    await writeFile(tmpPath, token + '\n', { mode: 0o600 });
+    await rename(tmpPath, tokenPath);
+  } catch (err) {
+    await rm(tmpPath, { force: true });
+    throw err;
+  }
+  log.warn(
+    { tokenPath },
+    'SETUP_TOKEN was not set — generated one for the first-boot setup wizard. ' +
+      `Use this token to claim the instance: ${token}  ` +
+      '(also readable inside the container at that path; set SETUP_TOKEN explicitly to choose your own)'
+  );
+  return token;
+}
+
+/** Best-effort removal of the generated token once the claim has succeeded. */
+export async function clearGeneratedSetupToken(dataDir: string): Promise<void> {
+  await rm(generatedSetupTokenPath(dataDir), { force: true });
+}

package/src/setup-transport.ts

@@ -0,0 +1,46 @@
+/**
+ * Transport guard for the one-shot first-boot wizard (PLT-10).
+ *
+ * `POST /api/v1/setup` carries the owner's password and the setup token. Over
+ * plaintext HTTP to a non-loopback origin both cross the network in the clear
+ * — and this is the single request that decides who owns the instance. The
+ * documented no-domain install path used to walk operators straight into
+ * exactly that, so the server refuses instead of trusting the runbook.
+ *
+ * Loopback is fine: nothing leaves the host, which is what makes the
+ * `ssh -L` tunnel a legitimate way to finish setup on a server with no TLS
+ * yet. `https` is fine anywhere. Everything else needs the conscious
+ * `ALLOW_INSECURE_SETUP=true` opt-in.
+ */
+export function isSecureSetupOrigin(publicBaseUrl: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(publicBaseUrl);
+  } catch {
+    // Unparseable never reaches here (the env schema validates a URL), and a
+    // guard that cannot read the origin must fail closed.
+    return false;
+  }
+  if (url.protocol === 'https:') return true;
+  return isLoopbackHost(url.hostname);
+}
+
+/**
+ * `URL.hostname` KEEPS the brackets around an IPv6 literal (`[::1]`), so they
+ * are stripped here. IPv4 loopback is the whole 127.0.0.0/8 block, not just
+ * 127.0.0.1. Exported for the demo sign-in's host rule
+ * (identity/demo-pass-rules.ts): one loopback test for the whole server.
+ */
+export function isLoopbackHost(hostname: string): boolean {
+  let host = hostname.toLowerCase();
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+  if (host === 'localhost' || host.endsWith('.localhost')) return true;
+  if (host === '::1' || host === '0:0:0:0:0:0:0:1') return true;
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (v4) {
+    const octets = v4.slice(1).map(Number);
+    if (octets.some((o) => o > 255)) return false;
+    return octets[0] === 127;
+  }
+  return false;
+}

package/src/state.ts

@@ -0,0 +1,23 @@
+/**
+ * Process-local runtime state. This is NOT application state (which lives in
+ * Postgres per the statelessness invariant) — it is the lifecycle of this one
+ * replica: readiness for /readyz and the draining flag for graceful shutdown.
+ */
+export interface RuntimeState {
+  ready: boolean;
+  reason: string;
+  draining: boolean;
+  /**
+   * A fail-closed boot verdict (PRDCT-1809): when set, every route except
+   * liveness, readiness and metrics answers 503 `service_closed` with this
+   * reason. Readiness alone does not stop the API — the single-host
+   * deployment's healthcheck watches /healthz — so a boot that found
+   * something it must not serve (an erasure it could not replay) closes the
+   * surface itself until an operator resolves it and restarts.
+   */
+  closed: string | null;
+}
+
+export function createRuntimeState(): RuntimeState {
+  return { ready: false, reason: 'booting', draining: false, closed: null };
+}

package/src/storage/driver.ts

@@ -0,0 +1,48 @@
+import type { Readable } from 'node:stream';
+
+/**
+ * The storage seam. Postgres never holds file bytes; every write goes
+ * through a driver. `local` (default) writes under DATA_DIR — valid for
+ * single-replica deployments; `s3` covers MinIO self-hosted and AWS/R2/GCS
+ * interop in cloud. Presigned-URL methods are deliberately reserved for a
+ * later revision (through-app streaming is the v1 contract).
+ */
+export interface ByteRange {
+  /** Inclusive start offset. */
+  start: number;
+  /** Inclusive end offset. */
+  end: number;
+}
+
+export interface PutOptions {
+  contentType: string;
+  sizeBytes: number;
+}
+
+export interface HeadResult {
+  sizeBytes: number;
+}
+
+export interface StorageDriver {
+  readonly name: 'local' | 's3';
+  put(key: string, data: Readable, opts: PutOptions): Promise<void>;
+  getStream(key: string, range?: ByteRange): Promise<Readable>;
+  exists(key: string): Promise<boolean>;
+  head(key: string): Promise<HeadResult | null>;
+  delete(key: string): Promise<void>;
+  /** Boot probe: throw when the backing store is not writable. */
+  healthcheck(): Promise<void>;
+}
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+
+/**
+ * Content-addressed key layout: `ws/<workspaceId>/<ab>/<sha256>`. The sha is
+ * validated against a strict hex pattern, so a key can never smuggle path
+ * traversal; the two-char shard keeps directories small at the 200GB target.
+ */
+export function blobKey(workspaceId: string, sha256: string): string {
+  if (!SHA256_RE.test(sha256)) throw new Error('invalid sha256');
+  if (!/^[0-9a-f-]{36}$/.test(workspaceId)) throw new Error('invalid workspace id');
+  return `ws/${workspaceId}/${sha256.slice(0, 2)}/${sha256}`;
+}

package/src/storage/factory.ts

@@ -0,0 +1,34 @@
+import { join } from 'node:path';
+import type { Env } from '../env.js';
+import type { StorageDriver } from './driver.js';
+import { LocalStorageDriver } from './local.js';
+import { S3StorageDriver } from './s3.js';
+
+export function createStorageDriver(
+  env: Pick<
+    Env,
+    | 'STORAGE_DRIVER'
+    | 'DATA_DIR'
+    | 'S3_BUCKET'
+    | 'S3_REGION'
+    | 'S3_ENDPOINT'
+    | 'S3_ACCESS_KEY_ID'
+    | 'S3_SECRET_ACCESS_KEY'
+    | 'S3_FORCE_PATH_STYLE'
+  >
+): StorageDriver {
+  if (env.STORAGE_DRIVER === 's3') {
+    if (!env.S3_BUCKET || !env.S3_ACCESS_KEY_ID || !env.S3_SECRET_ACCESS_KEY) {
+      throw new Error('STORAGE_DRIVER=s3 requires S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY');
+    }
+    return new S3StorageDriver({
+      bucket: env.S3_BUCKET,
+      region: env.S3_REGION ?? 'us-east-1',
+      endpoint: env.S3_ENDPOINT,
+      accessKeyId: env.S3_ACCESS_KEY_ID,
+      secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+      forcePathStyle: env.S3_FORCE_PATH_STYLE
+    });
+  }
+  return new LocalStorageDriver(join(env.DATA_DIR, 'storage'));
+}

package/src/storage/index.ts

@@ -0,0 +1,3 @@
+export { type StorageDriver, blobKey } from './driver.js';
+export { createStorageDriver } from './factory.js';
+export { LocalStorageDriver } from './local.js';

package/src/storage/local.ts

@@ -0,0 +1,93 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir, open, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, normalize, sep } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { randomUUID } from 'node:crypto';
+import type { Readable } from 'node:stream';
+import type { ByteRange, HeadResult, PutOptions, StorageDriver } from './driver.js';
+
+/** A missing file — the only fs error head()/delete() treats as "absent". */
+function isEnoent(err: unknown): boolean {
+  return (err as { code?: string })?.code === 'ENOENT';
+}
+
+/**
+ * Filesystem driver: blobs under `<root>/blobs`, writes staged in
+ * `<root>/.tmp` and renamed into place (atomic on one filesystem — both live
+ * under the same mount). Single-replica only, which is Profile A.
+ */
+export class LocalStorageDriver implements StorageDriver {
+  readonly name = 'local' as const;
+  private readonly blobRoot: string;
+  private readonly tmpRoot: string;
+
+  constructor(root: string) {
+    this.blobRoot = join(root, 'blobs');
+    this.tmpRoot = join(root, '.tmp');
+  }
+
+  private pathFor(key: string): string {
+    const path = normalize(join(this.blobRoot, key));
+    if (!path.startsWith(this.blobRoot + sep)) throw new Error('key escapes storage root');
+    return path;
+  }
+
+  async put(key: string, data: Readable, _opts: PutOptions): Promise<void> {
+    const finalPath = this.pathFor(key);
+    const tmpPath = join(this.tmpRoot, randomUUID());
+    await mkdir(this.tmpRoot, { recursive: true });
+    await mkdir(dirname(finalPath), { recursive: true });
+    try {
+      await pipeline(data, createWriteStream(tmpPath, { flags: 'wx' }));
+      await rename(tmpPath, finalPath);
+    } catch (err) {
+      await rm(tmpPath, { force: true });
+      throw err;
+    }
+  }
+
+  async getStream(key: string, range?: ByteRange): Promise<Readable> {
+    const path = this.pathFor(key);
+    // Open eagerly: a missing blob must reject HERE, at the await — before
+    // the caller commits response headers — not as a late 'error' event on a
+    // lazily-opening createReadStream after a 200 is already on the wire
+    // (the s3 driver's GetObject await fails eagerly too; this matches it).
+    const handle = await open(path, 'r');
+    // autoClose (default) hands fd ownership to the stream: closed on end,
+    // error, and destroy — including the route's client-abort destroy().
+    return handle.createReadStream(range ? { start: range.start, end: range.end } : {});
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return (await this.head(key)) !== null;
+  }
+
+  async head(key: string): Promise<HeadResult | null> {
+    try {
+      const s = await stat(this.pathFor(key));
+      return { sizeBytes: s.size };
+    } catch (err) {
+      // A missing file is `null`; any other stat error (permissions, I/O)
+      // propagates rather than masquerading as "absent".
+      if (isEnoent(err)) return null;
+      throw err;
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    // Deleting an already-gone blob is a no-op; real errors propagate and the
+    // caller decides whether they are fatal.
+    try {
+      await unlink(this.pathFor(key));
+    } catch (err) {
+      if (!isEnoent(err)) throw err;
+    }
+  }
+
+  async healthcheck(): Promise<void> {
+    await mkdir(this.tmpRoot, { recursive: true });
+    const probe = join(this.tmpRoot, `.healthcheck-${randomUUID()}`);
+    await writeFile(probe, 'ok');
+    await unlink(probe);
+  }
+}

package/src/storage/s3.ts

@@ -0,0 +1,109 @@
+import type { Readable } from 'node:stream';
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client
+} from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
+import { randomUUID } from 'node:crypto';
+import type { ByteRange, HeadResult, PutOptions, StorageDriver } from './driver.js';
+
+/** A missing object — the only S3 error head()/exists() treats as "absent". */
+function isNotFound(err: unknown): boolean {
+  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } };
+  return e?.name === 'NotFound' || e?.name === 'NoSuchKey' || e?.$metadata?.httpStatusCode === 404;
+}
+
+export interface S3DriverConfig {
+  bucket: string;
+  region: string;
+  endpoint?: string | undefined;
+  accessKeyId: string;
+  secretAccessKey: string;
+  /** Required for MinIO and most S3-compatibles. */
+  forcePathStyle: boolean;
+}
+
+/**
+ * S3-compatible driver: MinIO self-hosted, AWS S3, Cloudflare R2 (and any
+ * endpoint speaking the S3 API). Multi-replica safe — this is the Profile B
+ * storage driver.
+ */
+export class S3StorageDriver implements StorageDriver {
+  readonly name = 's3' as const;
+  private readonly client: S3Client;
+  private readonly bucket: string;
+
+  constructor(config: S3DriverConfig) {
+    this.bucket = config.bucket;
+    this.client = new S3Client({
+      region: config.region,
+      ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+      forcePathStyle: config.forcePathStyle,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      }
+    });
+  }
+
+  async put(key: string, data: Readable, opts: PutOptions): Promise<void> {
+    // lib-storage handles multipart for large bodies and backpressure.
+    const upload = new Upload({
+      client: this.client,
+      params: {
+        Bucket: this.bucket,
+        Key: key,
+        Body: data,
+        ContentType: opts.contentType,
+        ContentLength: opts.sizeBytes
+      }
+    });
+    await upload.done();
+  }
+
+  async getStream(key: string, range?: ByteRange): Promise<Readable> {
+    const res = await this.client.send(
+      new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        ...(range ? { Range: `bytes=${range.start}-${range.end}` } : {})
+      })
+    );
+    if (!res.Body) throw new Error('empty S3 response body');
+    return res.Body as Readable;
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return (await this.head(key)) !== null;
+  }
+
+  async head(key: string): Promise<HeadResult | null> {
+    try {
+      const res = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+      return { sizeBytes: res.ContentLength ?? 0 };
+    } catch (err) {
+      // Only a genuine miss is `null`. A transport/permission error must
+      // propagate — swallowing it made a broken bucket look like an empty one,
+      // and exists() (upload dedup) would then re-put or 400 misleadingly.
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    // S3 DeleteObject is idempotent (no error on a missing key); a real
+    // failure propagates and the caller decides whether it is fatal.
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+  }
+
+  async healthcheck(): Promise<void> {
+    const probe = `.healthcheck/${randomUUID()}`;
+    await this.client.send(
+      new PutObjectCommand({ Bucket: this.bucket, Key: probe, Body: 'ok', ContentLength: 2 })
+    );
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: probe }));
+  }
+}