@bridge_gpt/mcp-server 0.2.41 → 0.2.42

package/build/index-scope-contract.js

@@ -0,0 +1,96 @@
+/**
+ * The opaque index-scope declaration carried across a process boundary (BAPI-844).
+ *
+ * An index scope is the per-epic shadow index research is routed to. A pilot
+ * ticket has no `epic_ticket_status` / `epic_runs` row, so server-side membership
+ * discovery proves "non-epic" and routes to the canonical index — which is why the
+ * scope has to be DECLARED by the worker rather than discovered for it.
+ *
+ * This module owns the three names that declaration travels under, and nothing
+ * else:
+ *
+ * - {@link INDEX_SCOPE_ENV_VAR} — the worker environment variable,
+ * - {@link INDEX_SCOPE_HEADER} — the out-of-band Bridge API request header,
+ * - {@link validateOptionalIndexScope} — the shared shape check.
+ *
+ * TOKEN-OPAQUE BY CONSTRUCTION. The validator checks type, length, and shape and
+ * derives NOTHING from the value: not a repository, not a branch, not an epic run,
+ * not a shadow repository name. Those derivations are server-side, because the
+ * scope id is a server-minted identity (R14) and a worker that could compute a
+ * shadow name from it would be authorizing itself.
+ *
+ * VALIDATION IS NOT AUTHORIZATION. A well-formed declaration only means the value
+ * is shaped like a scope id. Whether the declaring worker may USE that scope is
+ * decided server-side, against the authenticated repository — see
+ * `api/agent_flows/code_writer/library/research_repo_resolver.py`. Nothing here
+ * may ever be read as a permission check.
+ */
+/**
+ * The environment variable a scoped worker carries.
+ *
+ * Deliberately NOT in `executor/env.ts`'s `ALLOWED_ENV_KEYS`, and explicitly on
+ * its `EXPLICIT_DENY_KEYS`: the value must arrive from an explicit, validated
+ * spawn option, never inherited from the executor's (or an operator's) ambient
+ * environment. This mirrors `BAPI_BASE_BRANCH` exactly — an ambient value that
+ * could override a run-scoped decision is the failure mode both keys avoid.
+ */
+export const INDEX_SCOPE_ENV_VAR = "BAPI_INDEX_SCOPE";
+/**
+ * The Bridge API request header a scoped MCP worker attaches.
+ *
+ * Out-of-band on purpose. Every request body keeps the CANONICAL `repo_name`,
+ * because repository identity is what authorization, configuration, billing, and
+ * Jira side effects are keyed by; only research RETRIEVAL consumes this header.
+ */
+export const INDEX_SCOPE_HEADER = "X-Bapi-Index-Scope";
+/**
+ * The server-minted scope-id shape: exactly 32 lowercase hexadecimal characters.
+ *
+ * Mirrors the server's own `_SCOPE_ID_RE` (`api/library/db/epic_shadow_index.py`),
+ * which is what `mint_scope_id()` (a `uuid4().hex`) produces. Anchored at both
+ * ends, so a longer string containing a valid token is rejected rather than
+ * partially matched.
+ */
+const INDEX_SCOPE_PATTERN = /^[0-9a-f]{32}$/;
+/**
+ * The ONE configuration-error message every malformed declaration produces.
+ *
+ * Fixed and value-free by design: an error that echoed the submitted value would
+ * push an opaque routing token into terminal output, worker logs, conductor
+ * events, and error reports — all places this token must never appear. Every
+ * rejection is therefore indistinguishable in its text, which is deliberate.
+ */
+export const INDEX_SCOPE_CONFIGURATION_ERROR = `${INDEX_SCOPE_ENV_VAR} is not a valid index-scope declaration. ` +
+    "Expected a server-minted scope identity; the value was not logged.";
+/** Thrown for a malformed declaration. Its message is always the fixed text above. */
+export class IndexScopeConfigurationError extends Error {
+    constructor() {
+        super(INDEX_SCOPE_CONFIGURATION_ERROR);
+        this.name = "IndexScopeConfigurationError";
+    }
+}
+/**
+ * Validate an OPTIONAL scope declaration.
+ *
+ * Returns `undefined` for an absent declaration (`undefined`, `null`, or an
+ * empty/blank string) — absence is the ordinary unscoped case and must stay
+ * indistinguishable from today's behavior. Returns a well-formed value BYTE-FOR-BYTE
+ * unchanged: no trimming, no case folding, no normalization, because a value the
+ * server minted is the only value the server will recognize.
+ *
+ * Throws {@link IndexScopeConfigurationError} for anything else, including a
+ * non-string. Failing loudly is the point: silently dropping a malformed
+ * declaration would route a scoped worker's research at the canonical index while
+ * every observable signal still said "scoped".
+ */
+export function validateOptionalIndexScope(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new IndexScopeConfigurationError();
+    if (value.trim().length === 0)
+        return undefined;
+    if (!INDEX_SCOPE_PATTERN.test(value))
+        throw new IndexScopeConfigurationError();
+    return value;
+}