@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/policy/engine.mjs

@@ -8,16 +8,24 @@
  * engine returns allow-without-approval everywhere.
  *
  * Decision precedence:
- *   1. Team-level decisions gate specialist decisions — forbidden by team blocks the action.
- *   2. Explicit deny in the role's fence → denied + typed reason.
- *   3. Action falls in the role's approvalRequired list → allowed but
+ *   0. Mandatory-audit gate (LMCP-H5) — enterprise only: if the audit sink is
+ *      down, every action is denied fail-closed before any other check runs.
+ *   1. Identity-anchored role authority (LMCP-I6) — in team/enterprise, an
+ *      env-claimed role not among the identity's registered grants is
+ *      denied before any manifest is consulted.
+ *   2. Team-level decisions gate specialist decisions — forbidden by team blocks the action.
+ *   3. Explicit deny in the role's fence → denied + typed reason.
+ *   4. Action falls in the role's approvalRequired list → allowed but
  *      approvalRequired = true (UI must collect human consent).
- *   4. risk === 'high' and role is not in HIGH_RISK_AUTONOMOUS → approval required.
- *   5. Otherwise → allowed.
+ *   5. risk === 'high' and role is not in HIGH_RISK_AUTONOMOUS → approval required.
+ *   6. Deny-by-default: team → deny unless explicit grant; enterprise → deny always.
+ *   7. solo → allowed.
  */
 
 import { readFileSync, existsSync } from 'node:fs';
 import { loadRegistry } from '../registry/loader.mjs';
+import { authorizeRoleClaim } from './role-authority.mjs';
+import { enforceMandatoryAudit } from './audit-gate.mjs';
 
 const HIGH_RISK_AUTONOMOUS = new Set(['security', 'sre', 'release-manager']);
 
@@ -97,6 +105,25 @@ function manifestFor(role, manifests) {
   return manifests?.personas?.[role] || null;
 }
 
+/**
+ * Return the default decision for unclassified (no matching explicit rule) tool calls.
+ *
+ * - solo       → 'allow'               (unchanged permissive behaviour)
+ * - team       → 'deny-unclassified'   (deny unless an explicit grant exists or the
+ *                                       user escapes with an approval flow)
+ * - enterprise → 'deny'               (hard deny regardless of approval escape)
+ *
+ * @param {'solo'|'team'|'enterprise'} deploymentMode
+ * @returns {'allow'|'deny-unclassified'|'deny'}
+ */
+export function getDefaultDecision(deploymentMode) {
+  switch (deploymentMode) {
+    case 'enterprise': return 'deny';
+    case 'team':       return 'deny-unclassified';
+    default:           return 'allow'; // solo and unknown → permissive
+  }
+}
+
 function actionMatches(pattern, action) {
   if (!pattern || !action) return false;
   if (pattern === action) return true;
@@ -125,15 +152,41 @@ function needsApprovalFromManifest(action, manifest) {
  * @param {string} input.action
  * @param {string} [input.decision] — optional decision id for team-level gate
  * @param {string} [input.risk]
+ * @param {'solo'|'team'|'enterprise'} [input.deploymentMode='solo'] — controls deny-by-default behaviour
+ * @param {object} [input.identity] — resolved actor/service identity (lib/identity.mjs). In
+ *   team/enterprise, `input.role` is validated as a claim against this identity's registered
+ *   grants (see lib/policy/role-authority.mjs) before any manifest lookup.
  * @param {object} [opts]
+ * @param {function} [opts.checkSink] — injectable audit-sink probe for LMCP-H5 tests;
+ *   defaults to the real fs-backed checkAuditSinkAvailable.
  * @returns {{allowed: boolean, reason: string, approvalRequired: boolean, source: string}}
  */
 export function policyDecision(input = {}, opts = {}) {
-  const { role, tool, action, decision, risk = 'low' } = input;
+  const { role, tool, action, decision, risk = 'low', deploymentMode = 'solo', identity } = input;
   if (!role) return { allowed: false, reason: 'role is required', approvalRequired: false, source: 'engine' };
   if (!tool) return { allowed: false, reason: 'tool is required', approvalRequired: false, source: 'engine' };
   if (!action) return { allowed: false, reason: 'action is required', approvalRequired: false, source: 'engine' };
 
+  const auditGateDecision = enforceMandatoryAudit({
+    deploymentMode,
+    ...(opts.checkSink ? { checkSink: opts.checkSink } : {}),
+  });
+  if (auditGateDecision) return auditGateDecision;
+
+  if ((deploymentMode === 'team' || deploymentMode === 'enterprise') && identity) {
+    if (identity.source === 'implicit-solo') {
+      return { allowed: false, reason: `Identity not resolved for ${deploymentMode} mode`, approvalRequired: false, source: 'identity-boundary' };
+    }
+
+    // Identity-anchored authority (LMCP-I6): the role claim under evaluation
+    // must be among the identity's registered grants — an env-declared role
+    // with no matching grant is denied before any manifest lookup runs.
+    const authority = authorizeRoleClaim({ identity, role, deploymentMode });
+    if (!authority.authorized) {
+      return { allowed: false, reason: authority.reason, approvalRequired: false, source: authority.source };
+    }
+  }
+
   const manifests = opts.manifests || loadRoleManifests(opts.manifestPath);
   const manifest = manifestFor(role, manifests);
 
@@ -186,6 +239,28 @@ export function policyDecision(input = {}, opts = {}) {
     };
   }
 
+  // Deny-by-default for team and enterprise modes.
+  // No explicit rule granted this action — consult the deployment-mode default.
+  const defaultDecision = getDefaultDecision(deploymentMode);
+  if (defaultDecision === 'deny') {
+    return {
+      allowed: false,
+      reason: 'deny-by-default',
+      approvalRequired: false,
+      mode: deploymentMode,
+      source: 'deny-by-default',
+    };
+  }
+  if (defaultDecision === 'deny-unclassified') {
+    return {
+      allowed: false,
+      reason: 'deny-by-default',
+      approvalRequired: false,
+      mode: deploymentMode,
+      source: 'deny-by-default',
+    };
+  }
+
   return {
     allowed: true,
     reason: `action "${action}" permitted for role "${role}"`,

package/lib/policy/role-authority.mjs

@@ -0,0 +1,89 @@
+/**
+ * lib/policy/role-authority.mjs — identity-anchored role claim authority.
+ *
+ * A6/ADR-0056 requires policy decisions to bind to actor/service identity
+ * (H2, lib/identity.mjs), not to a self-declared env var. Prior to this
+ * module, `CONSTRUCT_ROLE` alone selected the role manifest a caller was
+ * evaluated against — a worker could export the env var and claim any
+ * role's authority, including `security` or `release-manager`, with no
+ * check against who the identity actually is.
+ *
+ * `authorizeRoleClaim` closes that gap: it takes the resolved identity
+ * (from resolveIdentity()) and the role claim under evaluation, and
+ * decides whether the identity is entitled to act as that role.
+ *
+ * Registered-grants source: `identity.grants` — a list of role ids the
+ * identity is registered for. This is the seam LMCP-G5 (worker
+ * registration/heartbeat) and pack `toolGrantsRequested` (LMCP-E1) populate;
+ * neither exists as a live registration store yet, so until G5 lands the
+ * only way an identity acquires a grant is an explicit `identity.grants`
+ * array set by the caller that resolved the identity (e.g. from a signed
+ * header, a worker registration record, or test fixture). No implicit
+ * grants are invented here — an identity with no `grants` array has none.
+ *
+ * Mode behavior:
+ *   - solo: always authorized. CONSTRUCT_ROLE remains a documented
+ *     solo-only convenience (lib/identity.mjs env fallback); there is no
+ *     registration authority to check against in single-user mode.
+ *   - team / enterprise: the claimed role must be present in the
+ *     identity's `grants`. A role claim sourced from `env-fallback` (an
+ *     env var with no actor identity headers at all) is never itself
+ *     trusted as a grant — it is a claim, and claims are checked, not
+ *     trusted. Missing or non-matching grants are DENIED (fail closed).
+ */
+
+export class RoleAuthorityError extends Error {
+  constructor(message) { super(message); this.name = 'RoleAuthorityError'; }
+}
+
+/**
+ * Return the set of role ids an identity is registered for.
+ *
+ * `identity.grants` is the only source read today (see file header for
+ * why). Absent/malformed values resolve to an empty set — never to "all
+ * roles" — so a caller who forgets to populate grants fails closed rather
+ * than silently trusting the claim.
+ *
+ * @param {object} identity
+ * @returns {Set<string>}
+ */
+export function resolveIdentityGrants(identity) {
+  const grants = identity?.grants;
+  if (!Array.isArray(grants)) return new Set();
+  return new Set(grants.filter((g) => typeof g === 'string' && g.length > 0));
+}
+
+/**
+ * Decide whether `role` is an authorized claim for `identity` under
+ * `deploymentMode`.
+ *
+ * @param {object} input
+ * @param {object} input.identity - resolved identity (lib/identity.mjs shape)
+ * @param {string} input.role - the role claim under evaluation
+ * @param {'solo'|'team'|'enterprise'} [input.deploymentMode='solo']
+ * @returns {{authorized: boolean, reason: string, source: string}}
+ */
+export function authorizeRoleClaim({ identity, role, deploymentMode = 'solo' } = {}) {
+  if (!role) {
+    return { authorized: false, reason: 'role claim is required', source: 'role-authority' };
+  }
+
+  if (deploymentMode !== 'team' && deploymentMode !== 'enterprise') {
+    return { authorized: true, reason: 'solo mode: env-claimed role permitted (documented convenience)', source: 'solo-ergonomics' };
+  }
+
+  if (!identity) {
+    return { authorized: false, reason: `no identity resolved to validate role claim "${role}" in ${deploymentMode} mode`, source: 'role-authority' };
+  }
+
+  const grants = resolveIdentityGrants(identity);
+  if (grants.has(role)) {
+    return { authorized: true, reason: `role "${role}" is a registered grant for this identity`, source: 'identity-grant' };
+  }
+
+  return {
+    authorized: false,
+    reason: `role claim "${role}" is not in this identity's registered grants in ${deploymentMode} mode`,
+    source: 'role-authority.ungranted',
+  };
+}

package/lib/prompt-composer.js

@@ -39,7 +39,7 @@ import { estimateTokens, estimatePromptTokens, estimateTokensSync } from './toke
 import { cxDir } from './paths.mjs';
 import { getStrategyDigestSync } from './strategy-store.mjs';
 import { loadRegistry } from './registry/loader.mjs';
-import { bindingForSpecialist, resolveRoleOverlayId } from './roles/flavor-bindings.mjs';
+import { bindingForSpecialist, bindingsForSpecialistId, resolveRoleOverlayId } from './roles/flavor-bindings.mjs';
 
 const MAX_OBSERVATIONS = 3;
 
@@ -254,12 +254,23 @@ export function composePrompt(agentName, {
   }
 
   const shortName = String(agentName).replace(/^cx-/, '');
-  const flavorMapping = bindingForSpecialist(shortName);
 
   // When workspaceType is provided and roleFlavors doesn't already specify this agent's flavor,
   // auto-select the matching overlay so agents get domain guidance without requiring explicit caller config.
   const effectiveRoleFlavors = resolveRoleFlavors(roleFlavors, workspaceType, shortName);
 
+  // Since construct-rf26.11, one specialist can carry several flavor bindings
+  // (e.g. cx-engineer owns engineer/ai-engineer/platform-engineer/data-engineer
+  // overlays). Prefer whichever candidate binding's classifierKey the caller
+  // actually named in roleFlavors over the specialist's own bare-name binding,
+  // so a flavor-specific request (roleFlavors.platformEngineer) still resolves
+  // even though bindingForSpecialist(shortName) alone would only ever return
+  // the base 'engineer' entry.
+  const candidates = bindingsForSpecialistId(agentName);
+  const flavorMapping = (effectiveRoleFlavors
+    && candidates.find((b) => effectiveRoleFlavors[b.classifierKey]))
+    || bindingForSpecialist(shortName);
+
   if (flavorMapping && effectiveRoleFlavors) {
     const flavor = effectiveRoleFlavors[flavorMapping.classifierKey];
     if (flavor) {
@@ -276,7 +287,12 @@ export function composePrompt(agentName, {
           type: 'role-flavor',
           priority: PRIORITY['role-flavor'],
           label: roleId,
-          content: `### ${flavor === 'core' ? shortName : flavor} domain guidance\n\n${overlayContent}`,
+          // flavorMapping.rolePrefix (not the agent's own shortName) names the
+          // domain guidance: since construct-rf26.11 one specialist can carry
+          // several flavor bindings (e.g. cx-engineer), and shortName only
+          // ever reflects the specialist's own bare name, not which of its
+          // several possible overlays actually matched.
+          content: `### ${flavor === 'core' ? flavorMapping.rolePrefix : flavor} domain guidance\n\n${overlayContent}`,
           tokenBudget: selectedProfile.roleFlavorTokens,
         });
       }

package/lib/providers/contract/adapters/confluence/governed-write.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/providers/contract/adapters/confluence/governed-write.mjs —
+ * envelope-shaped Confluence write adapter.
+ *
+ * Wraps a Confluence REST transport in the provider shape
+ * lib/writes/envelope.mjs expects: write(config, payload), meta.id,
+ * search(). This is the only exposed entry point for Confluence writes —
+ * specialists and CLI callers route through writeWithEnvelope(), never
+ * through a raw Confluence client, so dedup, retry, dry-run, approval, and
+ * audit stay centralized in the envelope (LMCP-J2) rather than being
+ * reimplemented per-adapter.
+ *
+ * Adds the three behaviors a generic envelope cannot provide:
+ *
+ *   - Duplicate detection by title+space: before create, searches the
+ *     target space for an existing page with the same title (via the
+ *     injected `confluenceTransport.searchPagesByTitle`). A match returns a
+ *     `page-duplicate` result carrying a `linkback` to the existing page
+ *     instead of creating a second page — mirrors the GitHub adapter's
+ *     marker-search dedup (LMCP-J-github) but keyed on title+space rather
+ *     than a hidden marker, since Confluence page search has no analogue to
+ *     GitHub's full-text issue search over a hidden comment.
+ *   - Version-conflict recovery on update: Confluence page updates require
+ *     the current `version.number`; if the page changed since the caller
+ *     last fetched it, the API returns 409. On 409 this adapter refetches
+ *     the live page, re-renders the caller's update against the fresh
+ *     version, and returns a `version-conflict` result carrying the fresh
+ *     page and a `retryPayload` — the caller (or a human via the envelope's
+ *     approval path) re-approves before the adapter retries the write. The
+ *     adapter never blindly overwrites a page that changed underneath it.
+ *   - Linkback comment: after a successful create or update, posts a footer
+ *     comment on the page recording the write's idempotency key, so anyone
+ *     reading the page in Confluence can trace which governed write
+ *     produced or last touched it.
+ */
+
+import { AuthError } from '../../errors.mjs';
+
+const LINKBACK_PREFIX = 'construct:write:';
+
+function linkbackComment(idempotencyKey) {
+  return `<p>Published via Construct governed write (${LINKBACK_PREFIX}${idempotencyKey}).</p>`;
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.confluenceTransport - underlying Confluence REST transport; must implement
+ *   `searchPagesByTitle(spaceId, title)`, `getPage(pageId)`, `createPage(fields)`,
+ *   `updatePage(fields)`, `createFooterComment(pageId, body)`.
+ */
+export function createGovernedConfluenceProvider({ confluenceTransport } = {}) {
+  if (!confluenceTransport) throw new Error('createGovernedConfluenceProvider: confluenceTransport is required');
+
+  async function postLinkback(pageId, idempotencyKey) {
+    if (!idempotencyKey) return;
+    try {
+      await confluenceTransport.createFooterComment(pageId, linkbackComment(idempotencyKey));
+    } catch {
+      // Linkback is best-effort audit trail on the page itself; the
+      // envelope's sent-log is the authoritative record, so a comment
+      // failure must not fail an otherwise-successful publish.
+    }
+  }
+
+  async function writePage(payload) {
+    const { spaceId, title, body, parentId, idempotencyKey } = payload;
+    if (!spaceId) throw new Error('confluence governed write: payload.spaceId is required for type "page"');
+    if (!title) throw new Error('confluence governed write: payload.title is required for type "page"');
+
+    let existing;
+    try {
+      existing = await confluenceTransport.searchPagesByTitle(spaceId, title);
+    } catch (err) {
+      throw mapWriteTransportError(err, { spaceId });
+    }
+
+    const match = (existing ?? []).find((p) => p.title === title);
+    if (match) {
+      return {
+        type: 'page-duplicate',
+        id: match.id,
+        title: match.title,
+        url: match.url,
+        linkback: match.url,
+      };
+    }
+
+    try {
+      const result = await confluenceTransport.createPage({ spaceId, title, body, parentId });
+      await postLinkback(result.id, idempotencyKey);
+      return { type: 'page-created', id: result.id, title: result.title, version: result.version, url: result.url };
+    } catch (err) {
+      throw mapWriteTransportError(err, { spaceId });
+    }
+  }
+
+  async function writePageUpdate(payload) {
+    const { pageId, title, body, version, idempotencyKey } = payload;
+    if (!pageId) throw new Error('confluence governed write: payload.pageId is required for type "page-update"');
+    if (version === undefined || version === null) {
+      throw new Error('confluence governed write: payload.version is required for type "page-update"');
+    }
+
+    try {
+      const result = await confluenceTransport.updatePage({ pageId, title, body, version });
+      await postLinkback(pageId, idempotencyKey);
+      return { type: 'page-updated', id: result.id, title: result.title, version: result.version, url: result.url };
+    } catch (err) {
+      if (err?.status === 409) {
+        const fresh = await confluenceTransport.getPage(pageId);
+        return {
+          type: 'version-conflict',
+          id: pageId,
+          url: fresh.url,
+          currentVersion: fresh.version,
+          currentBody: fresh.body,
+          currentTitle: fresh.title,
+          retryPayload: {
+            type: 'page-update',
+            pageId,
+            title: title ?? fresh.title,
+            body,
+            version: fresh.version,
+            idempotencyKey,
+          },
+        };
+      }
+      throw mapWriteTransportError(err, { pageId });
+    }
+  }
+
+  return {
+    meta: {
+      id: 'confluence',
+      displayName: 'Confluence (governed)',
+      capabilities: ['write', 'search'],
+      description: 'Envelope-routed Confluence writes with title+space dedup, version-conflict recovery, and linkback comments.',
+    },
+
+    async write(config, payload) {
+      if (payload?.type === 'page') return writePage(payload);
+      if (payload?.type === 'page-update') return writePageUpdate(payload);
+      throw new Error(`confluence governed write: unsupported type "${payload?.type}" (only 'page' and 'page-update' are supported)`);
+    },
+
+    async search(config, query) {
+      const spaceId = typeof query === 'object' ? query?.spaceId : undefined;
+      const title = typeof query === 'object' ? query?.title : query;
+      return confluenceTransport.searchPagesByTitle(spaceId, title);
+    },
+
+    /**
+     * Render the payload the envelope would submit, without calling search,
+     * getPage, or the transport. Feeds the envelope's dry-run path
+     * (lib/writes/envelope.mjs `dryRun: true`), giving a human reviewing a
+     * pending write the exact storage-format body and target coordinates
+     * before anything is sent.
+     *
+     * @param {object} payload
+     * @returns {{ type: string, fields: object }}
+     */
+    renderDryRun(payload) {
+      if (payload?.type === 'page') {
+        return {
+          type: 'page',
+          fields: {
+            spaceId: payload.spaceId,
+            title: payload.title,
+            parentId: payload.parentId,
+            body: { representation: 'storage', value: payload.body },
+          },
+        };
+      }
+      if (payload?.type === 'page-update') {
+        return {
+          type: 'page-update',
+          fields: {
+            pageId: payload.pageId,
+            title: payload.title,
+            version: { number: payload.version },
+            body: { representation: 'storage', value: payload.body },
+          },
+        };
+      }
+      throw new Error(`confluence governed write: cannot render dry-run for unsupported type "${payload?.type}"`);
+    },
+  };
+}
+
+/**
+ * Map a create/update/search transport failure (401/403/404) to an
+ * actionable message. 409 (version conflict) is handled by the caller
+ * directly and never reaches this mapper.
+ *
+ * @param {Error & {status?: number}} err
+ * @param {{ spaceId?: string, pageId?: string }} ctx
+ * @returns {Error}
+ */
+function mapWriteTransportError(err, ctx) {
+  const status = err?.status;
+  if (status === 401) {
+    return new AuthError('Confluence authentication failed. Check CONFLUENCE_EMAIL / CONFLUENCE_TOKEN.', { provider: 'confluence' });
+  }
+  if (status === 403) {
+    const target = ctx.spaceId ? `space "${ctx.spaceId}"` : `page "${ctx.pageId}"`;
+    return new Error(`Forbidden: the authenticated account lacks permission to write to ${target}. Check the confluence-content:write scope.`);
+  }
+  if (status === 404) {
+    const target = ctx.spaceId ? `Space "${ctx.spaceId}"` : `Page "${ctx.pageId}"`;
+    return new Error(`${target} was not found, or the authenticated account cannot access it.`);
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+export default createGovernedConfluenceProvider;

package/lib/providers/contract/adapters/confluence/manifest.json

@@ -0,0 +1,17 @@
+{
+  "id": "confluence-write",
+  "version": "1.0.0",
+  "kind": "data-source",
+  "capabilities": ["write", "search"],
+  "secretEnvKeys": ["CONFLUENCE_URL", "CONFLUENCE_EMAIL", "CONFLUENCE_TOKEN"],
+  "operations": ["write:page", "write:page-update", "search"],
+  "securityClassification": "trusted",
+  "owner": "construct-core",
+  "compatVersion": 1,
+  "installSource": "builtin",
+  "exposure": "envelope-only",
+  "envelopeModule": "lib/writes/envelope.mjs",
+  "adapterModule": "lib/providers/contract/adapters/confluence/governed-write.mjs",
+  "transportModule": "lib/providers/contract/adapters/confluence/transport.mjs",
+  "notes": "Colocated write-capability manifest for LMCP-J4. Follows the lib/extensions/manifests/*.manifest.json schema (see atlassian-confluence.manifest.json, which declares read/search only). Wiring this into the shared lib/extensions/manifests/ discovery directory is out of scope for this bead; capabilities here are reachable only via writeWithEnvelope(), never a direct provider-registry lookup."
+}

package/lib/providers/contract/adapters/confluence/transport.mjs

@@ -0,0 +1,135 @@
+/**
+ * lib/providers/contract/adapters/confluence/transport.mjs — real Confluence
+ * Cloud REST v2 transport for the governed write adapter.
+ *
+ * Implements the `confluenceTransport` shape governed-write.mjs depends on:
+ * `searchPagesByTitle`, `getPage`, `createPage`, `updatePage`,
+ * `createFooterComment`. Kept separate from governed-write.mjs so tests can
+ * inject a fake transport (tests/fakes/fake-confluence-transport.mjs)
+ * without any network dependency, and separate from the read-oriented
+ * adapter in ./index.mjs so this write path never shares mutable state with
+ * the read path.
+ *
+ * Auth: API token via CONFLUENCE_URL + CONFLUENCE_EMAIL + CONFLUENCE_TOKEN
+ * env vars, or passed directly via config.
+ */
+
+import { AuthError, RateLimitError } from '../../errors.mjs';
+import { guardedFetch } from '../../../../net-guard.mjs';
+
+export function createConfluenceTransport(config = {}) {
+  const baseUrl = (config.baseUrl ?? process.env.CONFLUENCE_URL ?? '').replace(/\/$/, '');
+  const email = config.email ?? process.env.CONFLUENCE_EMAIL;
+  const token = config.token ?? process.env.CONFLUENCE_TOKEN;
+
+  if (!baseUrl || !email || !token) {
+    throw new AuthError(
+      'Confluence transport requires CONFLUENCE_URL, CONFLUENCE_EMAIL, and CONFLUENCE_TOKEN (or config.baseUrl/email/token)',
+      { provider: 'confluence' },
+    );
+  }
+
+  const auth = `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`;
+
+  // Egress runs through the N7 guard (SSRF/rebinding); a private-address
+  // self-hosted instance is an explicit, audited opt-in, never the default.
+  const allowPrivate = config.allowPrivateEgress ?? process.env.CONSTRUCT_NET_ALLOW_PRIVATE_EGRESS === '1';
+
+  async function request(path, { method = 'GET', body } = {}) {
+    const res = await guardedFetch(`${baseUrl}${path}`, {
+      method,
+      headers: {
+        Authorization: auth,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    }, { allowPrivate });
+
+    if (res.status === 429) {
+      const retryAfter = parseInt(res.headers.get('Retry-After') ?? '60', 10);
+      throw new RateLimitError('Confluence rate limit hit', { provider: 'confluence', retryAfter });
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      const err = new Error(`Confluence API ${method} ${path} failed: ${res.status} ${text.slice(0, 300)}`);
+      err.status = res.status;
+      throw err;
+    }
+    if (res.status === 204) return null;
+    return res.json();
+  }
+
+  return {
+    async searchPagesByTitle(spaceId, title) {
+      const params = new URLSearchParams({ title, 'space-id': spaceId, limit: '10' });
+      const data = await request(`/wiki/api/v2/pages?${params.toString()}`);
+      return (data.results ?? []).map((p) => ({
+        id: p.id,
+        title: p.title,
+        spaceId: p.spaceId,
+        version: p.version?.number ?? null,
+        url: `${baseUrl}${p._links?.webui ?? ''}`,
+      }));
+    },
+
+    async getPage(pageId) {
+      const data = await request(`/wiki/api/v2/pages/${pageId}?body-format=storage`);
+      return {
+        id: data.id,
+        title: data.title,
+        spaceId: data.spaceId,
+        version: data.version?.number ?? null,
+        body: data.body?.storage?.value ?? '',
+        url: `${baseUrl}${data._links?.webui ?? ''}`,
+      };
+    },
+
+    async createPage({ spaceId, title, body, parentId }) {
+      const reqBody = {
+        spaceId,
+        status: 'current',
+        title,
+        parentId: parentId ?? undefined,
+        body: { representation: 'storage', value: body },
+      };
+      const data = await request('/wiki/api/v2/pages', { method: 'POST', body: reqBody });
+      return {
+        id: data.id,
+        title: data.title,
+        version: data.version?.number ?? 1,
+        url: `${baseUrl}${data._links?.webui ?? ''}`,
+      };
+    },
+
+    async updatePage({ pageId, title, body, version }) {
+      const reqBody = {
+        id: pageId,
+        status: 'current',
+        title,
+        version: { number: version },
+        body: { representation: 'storage', value: body },
+      };
+      const data = await request(`/wiki/api/v2/pages/${pageId}`, { method: 'PUT', body: reqBody });
+      return {
+        id: data.id,
+        title: data.title,
+        version: data.version?.number ?? version,
+        url: `${baseUrl}${data._links?.webui ?? ''}`,
+      };
+    },
+
+    async createFooterComment(pageId, body) {
+      const data = await request('/wiki/api/v2/footer-comments', {
+        method: 'POST',
+        body: { pageId, body: { representation: 'storage', value: body } },
+      });
+      return {
+        id: data.id,
+        url: `${baseUrl}${data._links?.webui ?? ''}`,
+      };
+    },
+  };
+}
+
+export default createConfluenceTransport;