@stigmer/server 3.14.0-dev.20260910084630

package/src/artifactstorage/r2-storage.ts

@@ -0,0 +1,279 @@
+/**
+ * R2 artifact storage — ports pkg/domain/artifact/storage/r2_storage.go:
+ * the Cloudflare R2 (S3-compatible) backend, filling the factory arm #17
+ * deferred to this sub-project (owner-ratified, approved at the #13 plan
+ * gate together with the @aws-sdk dependency).
+ *
+ * Not conformance-assertable on the local targets (same as Go — the Go
+ * tree carries no R2 tests at all); the port adds unit pins for the pieces
+ * that have logic: config validation copy, the 7-day presign clamp, the
+ * signed Content-Disposition, and the not-found mapping.
+ */
+import { randomBytes } from "node:crypto";
+
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadBucketCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl as presignGetObject } from "@aws-sdk/s3-request-presigner";
+
+import type { ArtifactStorage, PresignedUpload } from "./artifact-storage.js";
+import {
+  ArtifactStorageNotFoundError,
+  contentDispositionAttachment,
+} from "./artifact-storage.js";
+
+/** Go: "R2 has a maximum expiration of 7 days" — presigns clamp here. */
+export const R2_MAX_EXPIRATION_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Key prefix for presignPut staging blobs (§6b). Pinned as the surface a
+ * deployment's bucket lifecycle rule targets: the driver mints under it,
+ * operations sweeps it — changing it orphans staged blobs from the sweep.
+ */
+export const R2_STAGING_PREFIX = "staging/";
+
+/**
+ * Go get_content/get_download_url wrap their storage calls in a 30s
+ * context timeout. The TS ArtifactStorage interface carries no signal, so
+ * the same bound lives one layer down, on the driver's network reads —
+ * identical ceiling, applied at the only backend where it can fire.
+ */
+const R2_CALL_TIMEOUT_MS = 30_000;
+
+export interface R2StorageConfig {
+  readonly bucket: string;
+  readonly endpoint: string;
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  /** Usually "auto" for R2 (Go default). */
+  readonly region: string;
+}
+
+/** Test seam: the two AWS clients, injectable for hermetic unit tests. */
+export interface R2Clients {
+  readonly client: S3Client;
+  readonly presign: typeof presignGetObject;
+}
+
+/**
+ * The exported R2 driver constructor (C1 seam, 20260827.04): a composition
+ * registers R2-backed drivers with ITS OWN config — the cloud's verified
+ * shape is distinct buckets/credentials per domain (blueprint §6b) — while
+ * the S3 plumbing, presign clamp, and not-found mapping live exactly once
+ * here. Loud-fail: the required-config throws below fire at driver
+ * construction, which the registered lazy factory defers to first use of
+ * the named driver (the factory contract in drivers.ts).
+ */
+export function newR2ArtifactStorage(config: R2StorageConfig): ArtifactStorage {
+  return new R2ArtifactStorage(config);
+}
+
+export class R2ArtifactStorage implements ArtifactStorage {
+  private readonly client: S3Client;
+  private readonly presign: typeof presignGetObject;
+  private readonly bucket: string;
+
+  constructor(config: R2StorageConfig, clients?: R2Clients) {
+    // Go NewR2Storage's required-config errors, byte-mirrored.
+    if (config.bucket === "") {
+      throw new Error("R2 bucket name is required");
+    }
+    if (config.endpoint === "") {
+      throw new Error("R2 endpoint is required");
+    }
+    if (config.accessKeyId === "") {
+      throw new Error("R2 access key ID is required");
+    }
+    if (config.secretAccessKey === "") {
+      throw new Error("R2 secret access key is required");
+    }
+
+    this.bucket = config.bucket;
+    if (clients !== undefined) {
+      this.client = clients.client;
+      this.presign = clients.presign;
+      return;
+    }
+    this.client = new S3Client({
+      region: config.region === "" ? "auto" : config.region,
+      endpoint: config.endpoint,
+      // R2 uses path-style addressing (Go o.UsePathStyle = true).
+      forcePathStyle: true,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey,
+      },
+    });
+    this.presign = presignGetObject;
+  }
+
+  async upload(key: string, data: Uint8Array, contentType: string): Promise<void> {
+    try {
+      await this.client.send(
+        new PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Body: data,
+          ...(contentType !== "" ? { ContentType: contentType } : {}),
+        }),
+      );
+    } catch (error) {
+      throw new Error(`r2 upload failed: ${errorText(error)}`, { cause: error });
+    }
+  }
+
+  async download(key: string): Promise<Uint8Array> {
+    let body: Uint8Array;
+    try {
+      const result = await this.client.send(
+        new GetObjectCommand({ Bucket: this.bucket, Key: key }),
+        { abortSignal: AbortSignal.timeout(R2_CALL_TIMEOUT_MS) },
+      );
+      if (result.Body === undefined) {
+        throw new Error("empty response body");
+      }
+      body = await result.Body.transformToByteArray();
+    } catch (error) {
+      // The typed not-found arm (O5): consumers mapping "missing" onto
+      // domain vocabulary branch on the class; every other failure stays
+      // the wrapped infrastructure fault it always was. Only the log-line
+      // text of the missing-object arm changes — every production caller
+      // wraps download faults in a sanitized Internal before the wire.
+      if (isNotFoundError(error)) {
+        throw new ArtifactStorageNotFoundError(key);
+      }
+      throw new Error(`r2 download failed: ${errorText(error)}`, { cause: error });
+    }
+    return body;
+  }
+
+  async size(key: string): Promise<number> {
+    try {
+      const result = await this.client.send(
+        new HeadObjectCommand({ Bucket: this.bucket, Key: key }),
+      );
+      return Number(result.ContentLength ?? 0);
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        throw new ArtifactStorageNotFoundError(key);
+      }
+      throw new Error(`r2 head failed: ${errorText(error)}`, { cause: error });
+    }
+  }
+
+  async presignPut(
+    declaredSizeBytes: number,
+    ttlMs: number,
+  ): Promise<PresignedUpload> {
+    const clampedMs = Math.min(ttlMs, R2_MAX_EXPIRATION_MS);
+    // Random staging key: the URL is the credential (unguessable), and the
+    // prefix is the contract surface a bucket lifecycle rule sweeps (§6b —
+    // staged uploads the domain never committed must not accrete forever).
+    const stagingKey = `${R2_STAGING_PREFIX}${randomBytes(16).toString("hex")}`;
+    const command = new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: stagingKey,
+      // Signed into the URL: a PUT whose body disagrees with the declared
+      // size fails the signature check — R2's arm of the exact-size
+      // contract the local lane enforces by counting bytes.
+      ContentLength: declaredSizeBytes,
+    });
+    try {
+      const url = await this.presign(this.client, command, {
+        expiresIn: Math.floor(clampedMs / 1000),
+      });
+      return { url, stagingKey, ttlMs: clampedMs };
+    } catch (error) {
+      throw new Error(`r2 presign failed: ${errorText(error)}`, { cause: error });
+    }
+  }
+
+  async getSignedUrl(
+    key: string,
+    expiresInMs: number,
+    downloadFilename: string,
+  ): Promise<string> {
+    const clampedMs = Math.min(expiresInMs, R2_MAX_EXPIRATION_MS);
+    const command = new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      // Go signs Content-Disposition into the presigned URL — the browser
+      // saves the object under the given name instead of rendering inline.
+      ...(downloadFilename !== ""
+        ? { ResponseContentDisposition: contentDispositionAttachment(downloadFilename) }
+        : {}),
+    });
+    try {
+      return await this.presign(this.client, command, {
+        expiresIn: Math.floor(clampedMs / 1000),
+      });
+    } catch (error) {
+      throw new Error(`r2 presign failed: ${errorText(error)}`, { cause: error });
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      await this.client.send(
+        new DeleteObjectCommand({ Bucket: this.bucket, Key: key }),
+      );
+    } catch (error) {
+      throw new Error(`r2 delete failed: ${errorText(error)}`, { cause: error });
+    }
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      await this.client.send(
+        new HeadObjectCommand({ Bucket: this.bucket, Key: key }),
+      );
+      return true;
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return false;
+      }
+      throw new Error(`r2 head failed: ${errorText(error)}`, { cause: error });
+    }
+  }
+
+  async health(): Promise<void> {
+    try {
+      await this.client.send(new HeadBucketCommand({ Bucket: this.bucket }));
+    } catch (error) {
+      throw new Error(`r2 health check failed: ${errorText(error)}`, {
+        cause: error,
+      });
+    }
+  }
+}
+
+/**
+ * Whether the error means "no such object" (Go isNotFoundError, adapted to
+ * the SDK's structured errors instead of Go's string matching): the S3
+ * NotFound/NoSuchKey names, an HTTP 404, or the legacy text forms.
+ */
+export function isNotFoundError(error: unknown): boolean {
+  if (error === null || error === undefined) {
+    return false;
+  }
+  const name = (error as { name?: string }).name ?? "";
+  if (name === "NotFound" || name === "NoSuchKey") {
+    return true;
+  }
+  const statusCode = (error as { $metadata?: { httpStatusCode?: number } })
+    .$metadata?.httpStatusCode;
+  if (statusCode === 404) {
+    return true;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("404") || message.includes("not found");
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/boot/__tests__/auth-enabled-composition.test.ts

@@ -0,0 +1,245 @@
+/**
+ * Pins the auth-enabled modeled state end to end (O3 rulings Q1+Q2+Q3)
+ * through the REAL stack: a composed server with STIGMER_OIDC_ISSUER
+ * pointing at a hermetic local issuer, real RS256 tokens, real gRPC.
+ *
+ * The full credential loop this proves is the multi-user self-host story:
+ *   1. tokenless requests are UNAUTHENTICATED "authentication token
+ *      missing" (the Java copy) — except is_public methods (getServerInfo)
+ *      and the gRPC health service by name (a Kubernetes grpc probe;
+ *      stigmer#974, entry 20260904.02);
+ *   2. an OIDC access token authenticates; the caller's sub becomes the
+ *      audit identity on resources it creates;
+ *   3. an API key minted over that OIDC session authenticates as its
+ *      owning user (the runner's credential lane, ruling Q3 — the runner
+ *      presents exactly such a key via STIGMER_TOKEN);
+ *   4. deleting the key revokes it on the very next request;
+ *   5. garbage credentials keep the Q6 unclaimed-token rejection.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createServer } from "node:http";
+import type { Server } from "node:http";
+import { once } from "node:events";
+
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import type { Client, Interceptor, Transport } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import { SignJWT, exportJWK, generateKeyPair } from "jose";
+import type { GenerateKeyPairResult } from "jose";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { ApiKeyCommandController } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/command_pb";
+import { ApiKeyQueryController } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/query_pb";
+import { PlatformQueryController } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import {
+  Health,
+  HealthCheckResponse_ServingStatus,
+} from "@stigmer/protos/grpc/health/v1/health_pb";
+
+import { loadConfig } from "../config.js";
+import { composeServer } from "../compose.js";
+import type { ComposedServer } from "../compose.js";
+import { createLogger } from "../logger.js";
+import { AUTHENTICATION_TOKEN_MISSING_MESSAGE } from "../../pipeline/interceptors/auth.js";
+
+const AUDIENCE = "https://api.stigmer.test/";
+
+let dir: string;
+let issuerServer: Server;
+let issuer: string;
+let privateKey: GenerateKeyPairResult["privateKey"];
+let server: ComposedServer;
+let port: number;
+
+function bearer(token: string): Interceptor {
+  return (next) => (request) => {
+    request.header.set("authorization", `Bearer ${token}`);
+    return next(request);
+  };
+}
+
+function transportWith(token?: string): Transport {
+  return createGrpcTransport({
+    baseUrl: `http://127.0.0.1:${port}`,
+    interceptors: token !== undefined ? [bearer(token)] : [],
+  });
+}
+
+async function mintOidcToken(sub: string, email: string): Promise<string> {
+  return new SignJWT({ email, name: "Composed Test User" })
+    .setProtectedHeader({ alg: "RS256", kid: "test-key" })
+    .setIssuer(issuer)
+    .setAudience(AUDIENCE)
+    .setSubject(sub)
+    .setIssuedAt()
+    .setExpirationTime("5m")
+    .sign(privateKey);
+}
+
+beforeAll(async () => {
+  const keys = await generateKeyPair("RS256");
+  privateKey = keys.privateKey;
+  const jwk = {
+    ...(await exportJWK(keys.publicKey)),
+    kid: "test-key",
+    alg: "RS256",
+  };
+  issuerServer = createServer((req, res) => {
+    if (req.url === "/.well-known/openid-configuration") {
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify({ issuer, jwks_uri: `${issuer}/jwks` }));
+      return;
+    }
+    if (req.url === "/jwks") {
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify({ keys: [jwk] }));
+      return;
+    }
+    res.statusCode = 404;
+    res.end();
+  });
+  issuerServer.listen(0, "127.0.0.1");
+  await once(issuerServer, "listening");
+  const address = issuerServer.address();
+  if (address === null || typeof address === "string") {
+    throw new Error("issuer server did not bind a port");
+  }
+  issuer = `http://127.0.0.1:${address.port}`;
+
+  dir = mkdtempSync(path.join(tmpdir(), "auth-enabled-test-"));
+  server = await composeServer({
+    config: loadConfig({
+      STIGMER_MODEL_REGISTRY_REFRESH: "off",
+      TEMPORAL_HOST_PORT: "127.0.0.1:1",
+      DB_PATH: path.join(dir, "stigmer.db"),
+      STORAGE_PATH: path.join(dir, "storage"),
+      ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+      STIGMER_OIDC_ISSUER: issuer,
+      STIGMER_OIDC_AUDIENCE: AUDIENCE,
+    }),
+    logger: createLogger({ level: "error", pretty: false, write: () => {} }),
+    portOverride: 0,
+    host: "127.0.0.1",
+  });
+  port = await server.start();
+});
+
+afterAll(async () => {
+  await server.shutdown();
+  issuerServer.close();
+  await once(issuerServer, "close");
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("the require-authentication posture on the wire", () => {
+  it("a tokenless RPC is UNAUTHENTICATED with the Java byte-pinned copy", async () => {
+    const query = createClient(ApiKeyQueryController, transportWith());
+    const error = await query.findAll({}).catch((e: unknown) => e);
+    expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
+    expect(ConnectError.from(error).rawMessage).toBe(
+      AUTHENTICATION_TOKEN_MISSING_MESSAGE,
+    );
+  });
+
+  it("is_public methods stay reachable tokenless (getServerInfo)", async () => {
+    const platform = createClient(PlatformQueryController, transportWith());
+    const info = await platform.getServerInfo({});
+    expect(info.edition).not.toBe("");
+  });
+
+  it("the gRPC health service stays reachable tokenless — a Kubernetes grpc probe survives the posture (stigmer#974)", async () => {
+    const health = createClient(Health, transportWith());
+    const response = await health.check({ service: "" });
+    expect(response.status).toBe(HealthCheckResponse_ServingStatus.SERVING);
+  });
+
+  it("a garbage bearer keeps the Q6 unclaimed-token rejection", async () => {
+    const query = createClient(
+      ApiKeyQueryController,
+      transportWith("not-a-credential"),
+    );
+    const error = await query.findAll({}).catch((e: unknown) => e);
+    expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
+    expect(ConnectError.from(error).rawMessage).toBe(
+      "the presented token was not accepted by any configured identity verifier",
+    );
+  });
+});
+
+describe("the full credential loop (OIDC login → API key → revocation)", () => {
+  let apiKeyPlaintext: string;
+  let apiKeyId: string;
+
+  it("an OIDC token authenticates and its sub becomes the audit identity", async () => {
+    const oidcToken = await mintOidcToken(
+      "auth0|loop-user",
+      "loop@example.com",
+    );
+    const command: Client<typeof ApiKeyCommandController> = createClient(
+      ApiKeyCommandController,
+      transportWith(oidcToken),
+    );
+    const created = await command.create({
+      apiVersion: "iam.stigmer.ai/v1",
+      kind: "ApiKey",
+      metadata: { name: "loop key", org: "local" },
+      spec: {},
+    });
+    apiKeyPlaintext = created.spec?.keyHash ?? "";
+    apiKeyId = created.metadata?.id ?? "";
+    expect(apiKeyPlaintext.startsWith("stk_")).toBe(true);
+    expect(created.status?.audit?.specAudit?.createdBy?.id).toBe(
+      "auth0|loop-user",
+    );
+    expect(created.status?.audit?.specAudit?.createdBy?.email).toBe(
+      "loop@example.com",
+    );
+  });
+
+  it("the minted API key authenticates as its owning user (the runner's lane)", async () => {
+    const query = createClient(
+      ApiKeyQueryController,
+      transportWith(apiKeyPlaintext),
+    );
+    const fetched = await query.get({ value: apiKeyId });
+    expect(fetched.metadata?.id).toBe(apiKeyId);
+
+    // A write over the key stamps the OWNER's identity on the audit — the
+    // key is the user, not a second principal.
+    const command = createClient(
+      ApiKeyCommandController,
+      transportWith(apiKeyPlaintext),
+    );
+    const second = await command.create({
+      apiVersion: "iam.stigmer.ai/v1",
+      kind: "ApiKey",
+      metadata: { name: "minted over the api key", org: "local" },
+      spec: {},
+    });
+    expect(second.status?.audit?.specAudit?.createdBy?.id).toBe(
+      "auth0|loop-user",
+    );
+  });
+
+  it("deleting the key revokes it on the very next request", async () => {
+    const oidcToken = await mintOidcToken(
+      "auth0|loop-user",
+      "loop@example.com",
+    );
+    const command = createClient(
+      ApiKeyCommandController,
+      transportWith(oidcToken),
+    );
+    await command.delete({ value: apiKeyId });
+
+    const query = createClient(
+      ApiKeyQueryController,
+      transportWith(apiKeyPlaintext),
+    );
+    const error = await query.findAll({}).catch((e: unknown) => e);
+    expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
+    expect(ConnectError.from(error).rawMessage).toBe("invalid token");
+  });
+});

package/src/boot/__tests__/compose.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Boot-ordering (health gate) tests — the contract the CLI's serverGate
+ * depends on (Go server.go:739-743, 839-843; grpc lib Stop :247-265):
+ *
+ *   - overall health is NOT_SERVING from construction until the
+ *     composition root completes;
+ *   - start() flips SERVING BEFORE the port binds, so the first probe that
+ *     reaches the port already sees a serving server;
+ *   - shutdown flips NOT_SERVING FIRST, then drains — and the port stops
+ *     answering.
+ */
+import { createClient } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import {
+  Health,
+  HealthCheckResponse_ServingStatus as ServingStatus,
+} from "@stigmer/protos/grpc/health/v1/health_pb";
+import { connect as netConnect } from "node:net";
+import { describe, expect, it } from "vitest";
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { loadConfig } from "../config.js";
+import { composeServer } from "../compose.js";
+import { createLogger } from "../logger.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+function compose() {
+  // Each composed server gets a throwaway database — the storage stage
+  // opens DB_PATH for real (never the developer's ~/.stigmer).
+  const testDir = mkdtempSync(path.join(tmpdir(), "compose-test-"));
+  const config = loadConfig({
+    STIGMER_MODEL_REGISTRY_REFRESH: "off",
+    // No engine behind composed tests: 127.0.0.1:1 is deterministically
+    // closed, so boots fail the non-fatal connect fast and can never touch
+    // a live local Temporal (the conformance CRUD harness does the same).
+    TEMPORAL_HOST_PORT: "127.0.0.1:1",
+    DB_PATH: path.join(testDir, "stigmer.db"),
+    // Keep the artifact store inside the test dir (never ~/.stigmer).
+    ARTIFACT_LOCAL_BASE_PATH: path.join(testDir, "artifacts"),
+    // Same for the skill artifact store — its boot-time staging wipe (#8)
+    // must never run against the real ~/.stigmer/storage.
+    STORAGE_PATH: path.join(testDir, "storage"),
+  });
+  return composeServer({
+    config,
+    logger: silentLogger,
+    portOverride: 0,
+    host: "127.0.0.1",
+  });
+}
+
+describe("composition-root boot ordering", () => {
+  it("is NOT_SERVING at construction and SERVING once the port answers", async () => {
+    const server = await compose();
+    expect(server.healthState.status("")).toBe(ServingStatus.NOT_SERVING);
+
+    const port = await server.start();
+    try {
+      const client = createClient(
+        Health,
+        createGrpcTransport({ baseUrl: `http://127.0.0.1:${port}` }),
+      );
+      // The serverGate contract: if the port accepts, health is already
+      // SERVING — there is no bound-but-not-ready window.
+      const response = await client.check({});
+      expect(response.status).toBe(ServingStatus.SERVING);
+    } finally {
+      await server.shutdown();
+    }
+  });
+
+  it("flips NOT_SERVING on shutdown and stops answering the port", async () => {
+    const server = await compose();
+    const port = await server.start();
+
+    await server.shutdown();
+
+    expect(server.healthState.status("")).toBe(ServingStatus.NOT_SERVING);
+    const refused = await new Promise<boolean>((resolve) => {
+      const probe = netConnect(port, "127.0.0.1");
+      probe.once("connect", () => {
+        probe.destroy();
+        resolve(false);
+      });
+      probe.once("error", () => resolve(true));
+    });
+    expect(refused, "the drained port must refuse new connections").toBe(true);
+  });
+});