@stigmer/server 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/archive/inflate.ts

@@ -0,0 +1,107 @@
+/**
+ * Reading one archive entry under a real cap. Declared sizes are client
+ * claims, so every gate that opens an entry bounds the ACTUAL inflated
+ * output (`maxOutputLength`), verifies the CRC the way Go's checksumReader
+ * does on every read, and opens only the two methods the platform
+ * registers (stored, deflated). The skill gate did this for SKILL.md alone;
+ * a plugin reads many documents through the same discipline, so the read
+ * lives here and each kind keeps its own sentences: the outcome is a typed
+ * failure, never prose, because the skill's copy is byte-pinned wire
+ * contract and a plugin's names a different document.
+ *
+ * Proven by __tests__/inflate.test.ts and, through composition, by the
+ * skill gate's zip-gate.test.ts.
+ */
+import { inflateRawSync } from "node:zlib";
+
+import { crc32 } from "@stigmer/zip-structure";
+import type { ZipStructuralEntry } from "@stigmer/zip-structure";
+
+/** ZIP compression methods the gate can open (Go registers the same two). */
+const METHOD_STORED = 0;
+const METHOD_DEFLATED = 8;
+
+export type InflateFailureKind =
+  /** The inflated output passed `maxSize`. */
+  | "too-large"
+  /** zlib refused the payload; `detail` carries its message. */
+  | "read-failed"
+  /** A compression method neither Go nor this gate registers. */
+  | "unsupported-method"
+  /** The inflated bytes do not match the entry's CRC. */
+  | "checksum";
+
+/** A typed refusal; the kind that called maps it to its pinned sentence. */
+export class InflateError extends Error {
+  constructor(
+    readonly kind: InflateFailureKind,
+    readonly detail: string,
+  ) {
+    super(`${kind}: ${detail}`);
+    this.name = "InflateError";
+  }
+}
+
+/**
+ * Inflates one entry to at most `maxSize` bytes and verifies its CRC.
+ * The cap bounds the actual output, not the declaration.
+ */
+export function inflateEntry(
+  entry: ZipStructuralEntry,
+  maxSize: number,
+): Uint8Array {
+  let content: Uint8Array;
+  switch (entry.compressionMethod) {
+    case METHOD_STORED:
+      content = entry.compressedData;
+      break;
+    case METHOD_DEFLATED:
+      try {
+        content = new Uint8Array(
+          inflateRawSync(entry.compressedData, {
+            maxOutputLength: maxSize + 1,
+          }),
+        );
+      } catch (error) {
+        if (isOutputLengthError(error)) {
+          throw new InflateError(
+            "too-large",
+            `output exceeds ${maxSize} bytes`,
+          );
+        }
+        throw new InflateError(
+          "read-failed",
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+      break;
+    default:
+      // Go: File.Open returns ErrAlgorithm for methods without a registered
+      // decompressor; each kind pins the text via its own %w-shaped arm.
+      throw new InflateError(
+        "unsupported-method",
+        "zip: unsupported compression algorithm",
+      );
+  }
+
+  if (content.length > maxSize) {
+    throw new InflateError("too-large", `output exceeds ${maxSize} bytes`);
+  }
+
+  if (crc32(content) !== entry.crc32) {
+    // Go's checksumReader: stdlib ErrChecksum via the read-error arm.
+    throw new InflateError("checksum", "zip: checksum error");
+  }
+
+  return content;
+}
+
+/** node:zlib's maxOutputLength violation (the output-cap arm). */
+function isOutputLengthError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (("code" in error &&
+      (error as { code?: string }).code === "ERR_BUFFER_TOO_LARGE") ||
+      error.message.includes("maxOutputLength"))
+  );
+}

package/src/archive/limits.ts

@@ -0,0 +1,42 @@
+/**
+ * The platform's archive limits — one home for every ZIP-bomb budget the
+ * server applies to a pushed archive, whichever kind it becomes. Skills
+ * carried these alone until plugins arrived (also pushed as a ZIP); the
+ * values stay byte-pinned to the retired Go gate's (pkg/domain/skill/storage/
+ * zip_extractor.go), because every sentence quoting them is wire contract
+ * and the transfer lane refuses over-limit declarations by them before a
+ * byte moves.
+ *
+ * A per-kind cap that is NOT an archive budget (the 1 MB SKILL.md
+ * extraction cap) stays with its kind: it bounds one document, not the
+ * archive.
+ */
+
+/**
+ * The compressed-archive ceiling. The platform's artifact size limit, not
+ * just an extraction guard: createArtifactUploadUrl enforces it before any
+ * bytes move and clients quote it in fail-loud size errors (#675).
+ */
+export const MAX_ZIP_SIZE = 100 * 1024 * 1024;
+
+/** Total declared-uncompressed budget across all entries (ZIP-bomb guard). */
+export const MAX_UNCOMPRESSED_SIZE = 500 * 1024 * 1024;
+
+/** Per-file declared compression ratio ceiling (ZIP-bomb guard). */
+export const MAX_COMPRESSION_RATIO = 100;
+
+/** Entry-count ceiling. */
+export const MAX_FILES = 10_000;
+
+/** The budgets `validateArchiveStructure` applies; the platform's by default. */
+export interface ArchiveLimits {
+  readonly maxFiles: number;
+  readonly maxUncompressedSize: number;
+  readonly maxCompressionRatio: number;
+}
+
+export const PLATFORM_ARCHIVE_LIMITS: ArchiveLimits = {
+  maxFiles: MAX_FILES,
+  maxUncompressedSize: MAX_UNCOMPRESSED_SIZE,
+  maxCompressionRatio: MAX_COMPRESSION_RATIO,
+};

package/src/archive/open.ts

@@ -0,0 +1,131 @@
+/**
+ * Opening a pushed archive — the kind-agnostic half of the ZIP gate every
+ * archive-shaped push runs (skills, plugins). Two steps, both pure over the
+ * bytes: `openArchive` bounds the compressed size, hashes the bytes (the
+ * content-addressed version identity), parses the central directory and
+ * applies the safearchive prefilter; `validateArchiveStructure` walks the
+ * pre-filtered entries in the retired Go gate's exact order (empty
+ * archive, file count, then per entry the filename control-character rule,
+ * the running declared-uncompressed budget and the per-file ratio cap).
+ *
+ * What a KIND requires of the entries (a root SKILL.md, a plugin manifest)
+ * is not here: the walk accepts an `onEntry` observer so a kind tracks what
+ * it needs in the same pass and rules on it afterwards, which keeps the
+ * observable error order the skill gate's tests pin.
+ *
+ * Error text is wire-visible contract: the sentences below are the Go
+ * gate's verbatim, wrapped by each kind's push step into its own
+ * InvalidArgument arm. Only declared sizes are judged here; inflating an
+ * entry under a real cap is `inflate.ts`'s job.
+ *
+ * Proven by the skill gate's __tests__/zip-gate.test.ts (which composes
+ * these) and by __tests__/open.test.ts for the plugin-shaped path.
+ */
+import { createHash } from "node:crypto";
+
+import { parseZipStructure } from "@stigmer/zip-structure";
+import type { ZipStructuralEntry } from "@stigmer/zip-structure";
+
+import type { ArchiveLimits } from "./limits.js";
+import { MAX_ZIP_SIZE } from "./limits.js";
+import { applyEntryPrefilter } from "./prefilter.js";
+import type { PrefilteredEntry } from "./prefilter.js";
+
+/** A parsed, pre-filtered archive with its content-addressed identity. */
+export interface OpenedArchive {
+  /** SHA-256 hex of the archive bytes. */
+  readonly hash: string;
+  /** The entries a kind may read, names sanitised, shadows dropped. */
+  readonly entries: readonly PrefilteredEntry[];
+}
+
+/**
+ * Bounds, hashes, parses and pre-filters. Throws plain Errors with
+ * byte-pinned messages; the caller owns the gRPC code.
+ */
+export function openArchive(
+  bytes: Uint8Array,
+  maxZipSize: number = MAX_ZIP_SIZE,
+): OpenedArchive {
+  if (bytes.length > maxZipSize) {
+    throw new Error(
+      `ZIP file too large: ${bytes.length} bytes (max: ${maxZipSize})`,
+    );
+  }
+
+  const hash = calculateHash(bytes);
+
+  let entries: readonly ZipStructuralEntry[];
+  try {
+    entries = parseZipStructure(bytes);
+  } catch {
+    // Go's zip.NewReader surfaces stdlib ErrFormat here; its text is what
+    // clients see via the %w chain, so it is pinned verbatim.
+    throw new Error("invalid ZIP file: zip: not a valid zip file");
+  }
+
+  // safearchive MaximumSecurityMode rewrites the entry list before any
+  // validation sees it — sanitized names, shadowed/special/8.3 entries
+  // dropped.
+  return { hash, entries: applyEntryPrefilter(entries) };
+}
+
+/**
+ * The structural walk: empty archive, file-count cap, then per entry the
+ * control-character rule, the running declared-uncompressed budget
+ * (fail-fast) and the per-file compression-ratio cap. `onEntry` sees each
+ * sanitised name in order so a kind can track its own requirements.
+ */
+export function validateArchiveStructure(
+  entries: readonly PrefilteredEntry[],
+  limits: ArchiveLimits,
+  onEntry?: (name: string) => void,
+): void {
+  if (entries.length === 0) {
+    throw new Error("ZIP file is empty");
+  }
+
+  if (entries.length > limits.maxFiles) {
+    throw new Error(
+      `too many files in ZIP: ${entries.length} (max: ${limits.maxFiles})`,
+    );
+  }
+
+  let totalUncompressedSize = 0;
+
+  for (const { name, entry } of entries) {
+    onEntry?.(name);
+
+    // Reject null bytes and control characters in entry names (code
+    // points, not UTF-16 units — Go ranges over runes).
+    for (const ch of name) {
+      const codePoint = ch.codePointAt(0)!;
+      if (codePoint < 32 || codePoint === 127) {
+        throw new Error(`invalid character in filename: ${name}`);
+      }
+    }
+
+    // Track the declared uncompressed total (fail fast once exceeded).
+    totalUncompressedSize += entry.uncompressedSize;
+    if (totalUncompressedSize > limits.maxUncompressedSize) {
+      throw new Error(
+        `total uncompressed size too large: ${totalUncompressedSize} bytes (max: ${limits.maxUncompressedSize})`,
+      );
+    }
+
+    // Per-file compression ratio (ZIP-bomb guard); integer division as Go.
+    if (entry.compressedSize > 0) {
+      const ratio = Math.floor(entry.uncompressedSize / entry.compressedSize);
+      if (ratio > limits.maxCompressionRatio) {
+        throw new Error(
+          `suspicious compression ratio in ${name}: ${ratio}:1 (max: ${limits.maxCompressionRatio}:1)`,
+        );
+      }
+    }
+  }
+}
+
+/** SHA-256 hex of the archive bytes (Go CalculateHash). */
+export function calculateHash(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}

package/src/{domain/skill/storage → archive}/prefilter.ts

@@ -28,6 +28,11 @@
  * bits; FAT/NTFS/VFAT creators carry MSDOS bits that can never encode a
  * symlink or special file; unknown creators decode to a regular file.
  *
+ * Shared by every archive gate the server runs (skills, plugins): the
+ * filter describes what an archive IS before any kind reads it, so it
+ * lives with the archive plumbing rather than with the first kind that
+ * needed it.
+ *
  * Proven by __tests__/prefilter.test.ts (byte-crafted fixtures per DD-001).
  */
 import type { ZipStructuralEntry } from "@stigmer/zip-structure";

package/src/archive/write.ts

@@ -0,0 +1,54 @@
+/**
+ * Writing a deterministic archive. The server writes ZIPs for one reason: a
+ * plugin's skills are pushed through the skill pipeline as archives of
+ * their own, and a skill's version IS the SHA-256 of its archive bytes, so
+ * the same files must always produce the same bytes or every re-install
+ * would mint a new skill version out of nothing. Determinism comes from
+ * three choices, each mirrored from the CLI's skill packager
+ * (client-apps/cli/src/resources/skill.ts): entries sorted by path, one
+ * fixed DOS-epoch mtime on every entry (fflate would otherwise stamp the
+ * wall clock), and one fixed deflate level.
+ *
+ * fflate is the ratified server dependency for ZIP work (see
+ * domain/agentexecution/artifacts.ts); this module is its one write site.
+ *
+ * Proven by __tests__/write.test.ts: two writes of the same files are
+ * byte-equal, entry order does not matter, and the result round-trips
+ * through the server's own reader.
+ */
+import { zipSync } from "fflate";
+
+/** One file to write: a plugin-relative POSIX path and its bytes. */
+export interface ArchiveFile {
+  readonly path: string;
+  readonly bytes: Uint8Array;
+}
+
+/**
+ * fflate stamps the archive's creation time into every entry when no mtime
+ * is given; pinning the DOS epoch removes the one source of byte-level
+ * variance. Local-field construction is deliberate: DOS timestamps are
+ * local time, and this instant is representable in every zone.
+ */
+const DETERMINISTIC_ZIP_MTIME = new Date(1980, 0, 1);
+
+/** The CLI's level; changing it would move every digest in the field. */
+const DEFLATE_LEVEL = 6;
+
+/** Writes `files` as one deflated archive whose bytes depend on the files alone. */
+export function writeArchive(files: ReadonlyArray<ArchiveFile>): Uint8Array {
+  const sorted = [...files].sort((a, b) =>
+    a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+  );
+  const tree: Record<string, Uint8Array> = {};
+  for (const file of sorted) {
+    if (file.path in tree) {
+      throw new Error(`archive path '${file.path}' listed twice`);
+    }
+    tree[file.path] = file.bytes;
+  }
+  return zipSync(tree, {
+    level: DEFLATE_LEVEL,
+    mtime: DETERMINISTIC_ZIP_MTIME,
+  });
+}

package/src/authorization/README.md

@@ -0,0 +1,124 @@
+# authorization/ — the built-in authorizer
+
+Open source's own `Authorizer`, organization directory, schedule fire caller and
+`ListReadScope`, composed when a server runs under an authentication posture and
+no unit registers its own — the **built-in posture** (`posture.ts`; the other
+two are the trusted-local laptop's permissive default and a unit's own
+Authorizer). It is not a domain: it drives ports the registry declares
+(`extensions/authorizer.ts`, `extensions/organization-directory.ts`,
+`extensions/schedule-fire-caller.ts`, `extensions/list-read-scope.ts`) by
+reading aggregates it does not own — resources through the generic `Store`,
+accounts through the `IdentityAccountStore` port, roles through the
+`IamPolicyStore` port — and writes nothing.
+
+The idea, once: in the cloud, authorization is the OpenFGA model evaluated over
+stored tuples, and every tuple is derived from a row by
+`kind_meta.authorization` except the one that is a fact, the IamPolicy row. So
+open source evaluates the same model over the same tuples, derived from the row
+when a check asks instead of stored. One meaning of authorization in both
+editions; the cloud stores what open source computes.
+
+## Parts
+
+- `model/rewrite.ts` — the four relation-rewrite forms the 27 `.fga` files use
+  (`this` with its type restrictions, `computed`, `from`, `union`), the
+  builders, and `declareKind`, which refuses a transcript that cannot be right
+  at module load.
+- `model/<kind>.ts` — one transcript per open-source kind (twenty-three), the
+  `.fga` file's relations in the file's order, its path in the header.
+  `model/index.ts` registers them in `fga.mod` order and answers by kind or by
+  FGA type name. Two relations no row carries as a `kind_meta` fact have a
+  `derived` rule beside their transcript: `default_of` on the two instance kinds
+  (`model/default-of.ts`, from the blueprint's `status.default_instance_id`) and
+  `execution_viewer` on the workflow instance (from
+  `spec.execution_visibility`).
+- `tuples.ts` — the tuple vocabulary (object, relation, subject; the string
+  notation), the `Person` type (the caller as the model sees them: account id
+  plus the aliases a creator stamp may carry), `CheckContext` (the
+  `allow_public` parameter: `allow: true` on a point check, `false` in a listing
+  — the cloud's own posture).
+- `person.ts` — the one construction of a `Person`: `resolvePerson` reads the
+  caller's account through the port the way whoAmI does, `personFor` builds the
+  aliases (the account id and the issuer subject; an email is nobody's) and
+  refuses an identity that names no person. Every driver resolves the caller
+  here.
+- `evaluator.ts` — OpenFGA's check over a model and a tuple source: type
+  restrictions enforced on direct tuples (model drift fails closed), a memo per
+  (object, relation), OpenFGA's depth bound, cycles and undeclared targets as
+  faults, never silent denials.
+- `facts.ts` — `RowFacts`, what a row carries that its tuples derive from: the
+  seam's `RowAuthorizationFacts` with the kind beside them. Two producers, one
+  resolver: a loaded row (`rowFactsOf`) and a list candidate (`rowFactsOfEntry`
+  over the `ListEntryMeta` the lanes' helper builds) both read through the
+  pipeline leaf `pipeline/steps/authorization-facts.ts`, the read-time twin of
+  the tuple lifecycle's create-time resolution, pinned equal to it.
+- `derived-tuples.ts` — the derivation (the cloud driver's shapes, from the
+  facts) and the source that joins it with the person's IamPolicy rows, read
+  once per source. The two edition-specific facts live here: the organization's
+  owner is a row, and a stamp that names no person is no tuple. A source may be
+  seeded with candidates' facts (the list scope), so a seeded object's tuples
+  derive without a read of its row; a `derived` rule still reads the row it
+  needs.
+- `store-test-kit.ts` — runs an OpenFGA store test (`.fga.yaml`) against the
+  evaluator, vitest-free, exported from the barrel. Open source runs it over
+  pinned copies of the cloud's own model tests (`__tests__/fixtures/fga/`, a
+  byte-exact mirror of the cloud's `fga/tests/`); the cloud runs it over the
+  live files at the re-pin. What it does not run it reports in three reasons: a
+  target kind the model does not declare, a `list_objects` assertion, and an
+  assertion whose walk read a grant through a type the model does not declare
+  (the cloud's platform tenancy, `identity_provider#platform_user`).
+
+- `authorizer.ts` — the `Authorizer` driver, arm for arm the cloud's
+  (`stigmer-cloud src/authorizer/fga-authorizer.ts`): the four pre-check denials
+  with the Java copy; a kind this edition does not serve denied (so nobody sets
+  public visibility on a self-host); the target loaded once through the source;
+  `not-found` for a missing row except on the kinds the cloud never probes
+  (`NOT_FOUND_EXEMPT_KINDS`: `identity_account`, `iam_policy` — account ids
+  cannot be enumerated); the model's answer with an empty reason on a denial so
+  the annotation's copy wins; every fault `unavailable`, never a denial and
+  never a throw.
+- `organization-directory.ts` — `findMyOrganizations` as the cloud answers it
+  (`listObjectIds(can_view, organization)`): the organizations the person's rows
+  name, kept when `can_view` holds; the `internal` class sees all (the
+  in-process authorization skip); enumeration refused.
+- `schedule-fire-caller.ts` — a fire acts as the schedule's creator, resolved
+  from the row's stamp as an account id or as the 3.14.x raw subject; a stamp
+  that names no person is the seam's deterministic refusal, which the RunStarter
+  counts against the schedule instead of retrying forever.
+- `list-read-scope.ts` — the `ListReadScope` driver, the cloud's twin
+  (`stigmer-cloud src/iam/list-read-scope.ts`): every candidate a list lane
+  offers is answered by `can_view` under the listing context (`allow: false`,
+  the public wildcard suppressed) — one evaluator walk per candidate over one
+  source seeded with the candidates' facts, so no candidate row is read twice
+  and a parent hop reads each distinct parent once; the enumeration verb
+  (search, recent activity, the two execution summaries — the console library
+  rides it) scans the kind and evaluates the same way, a row that does not
+  decode skipped; the `internal` class keeps everything (the in-process skip); a
+  fault throws and is never an empty answer; an undeclared kind is a consumer
+  bug, loud.
+- `posture.ts` — the three postures, named once for the composition root and the
+  boot log.
+
+## Proof
+
+`__tests__/store-tests.test.ts` is the proof that this evaluator answers the
+cloud's model the cloud's way: every `checkRelation` assertion of all twenty
+documents on a declared kind, in the documents' own words, with what is not run
+pinned as a named list. `__tests__/facts.test.ts` pins that the derivation reads
+a row to the same links and shapes the tuple lifecycle writes from, for every
+kind. `model/__tests__/registry.test.ts` pins the declared set to the
+open-source tier and each kind's wire permissions to its file;
+`__tests__/wire-permissions.test.ts` pins that every static `(kind, permission)`
+a served RPC asks about is a declared relation. The rest pin the machinery:
+alias matching, the wildcard's condition, the memo, the bounds, the source and
+the two derived rules on both store drivers. The four drivers are pinned arm by
+arm on both store drivers (`__tests__/authorizer.test.ts`,
+`organization-directory.test.ts`, `schedule-fire-caller.test.ts`,
+`list-read-scope.test.ts` — the adversarial cells first: the outsider, the
+viewer rung, the admin who does not read members' conversations, the orphaned
+execution, the memory with no subject), the posture at the wire over three real
+boots (`extensions/__tests__/built-in-authorization-composed.test.ts`, the list
+lanes included, and the two-boot proof that the sole person's lists are
+byte-identical with and without the scope), and the scope's cost is measured
+rather than assumed (`list-read-scope.measure.test.ts`, gated on
+`AUTHORIZATION_MEASURE=1`).