@openwop/openwop-conformance 1.10.0 → 1.12.0

package/src/scenarios/oauth-authorization-code-roundtrip.test.ts

@@ -0,0 +1,145 @@
+/**
+ * oauth-authorization-code-roundtrip — RFC 0047 §C (the authorization-code grant
+ * end-to-end) + §C.2 / `credential-payload-redaction`.
+ *
+ * Closes the RFC 0047 Tier-2 gap: `oauth-capability-shape` proves the discovery
+ * block is well-formed and `oauth-connector-redaction` proves an already-acquired
+ * token doesn't leak — but nothing exercised the actual authorization-code DANCE
+ * (redirect → callback → token exchange) against a known provider. This scenario
+ * drives that roundtrip against ONE canonical synthetic provider whose endpoints a
+ * conformance test double serves, so a host can prove the grant without a live IdP.
+ *
+ * The synthetic provider + its canned exchange are defined in
+ * `fixtures/oauth-providers/synthetic.json`; the constants below mirror it (kept
+ * inline so the scenario runs from the published tarball without fixture-path
+ * resolution, exactly like `oauth-connector-redaction`'s TOKEN_CANARY).
+ *
+ * Capability-gated: skips unless the host advertises
+ * `capabilities.oauth.supported = true` AND lists `authorization_code` in
+ * `capabilities.oauth.grants`. Behavioral probe drives the optional host seam
+ * `POST /v1/host/sample/oauth/authorize-code-roundtrip`; a 404 (seam not wired)
+ * is a soft-skip — this is a Tier-2 host-pending scenario.
+ *
+ * Asserts, when the seam is present:
+ *   1. The roundtrip succeeds and returns a credential REFERENCE (the token was
+ *      acquired + persisted as a host.credentials entry), never the token itself.
+ *   2. `connector.authorized` carries `{ provider, credentialRef, scopes }` and
+ *      none of the token / refresh / code / state / redirectUri / codeVerifier.
+ *   3. RFC 0047 §C — the authorization code, redirect URI, state, and PKCE
+ *      verifier MUST NOT appear on ANY run-visible surface; §C.2 — neither MUST
+ *      the access/refresh token (the canaries are absent from the whole response).
+ *
+ * @see RFCS/0047-host-oauth-connector-flows.md §C
+ * @see conformance/fixtures/oauth-providers/synthetic.json
+ * @see SECURITY/invariants.yaml id: credential-payload-redaction
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+interface DiscoveryOAuth {
+  supported?: boolean;
+  grants?: string[];
+}
+
+// Mirrors fixtures/oauth-providers/synthetic.json — keep in sync.
+const SYNTHETIC = {
+  provider: 'synthetic',
+  authUrl: 'https://oauth.synthetic.openwop.test/authorize',
+  tokenUrl: 'https://oauth.synthetic.openwop.test/token',
+  scopes: ['openwop.read', 'openwop.write'],
+  authorizationCode: 'openwop-synthetic-auth-code-1f4b9e',
+  state: 'openwop-synthetic-state-7c2a8d',
+  redirectUri: 'https://host.example/openwop/oauth/callback',
+  codeVerifier: 'openwop-synthetic-pkce-verifier-3e9f1b2c5a7d4e8f0a1b2c3d4e5f6a7b',
+  accessTokenCanary: 'OPENWOP_OAUTH_TOKEN_CANARY_9d4c1f7a',
+  refreshTokenCanary: 'OPENWOP_OAUTH_REFRESH_CANARY_2b8e6a3f',
+} as const;
+
+// Values that MUST NOT appear on any run-visible surface (RFC 0047 §C + §C.2).
+const SECRET_VALUES: readonly string[] = [
+  SYNTHETIC.accessTokenCanary,
+  SYNTHETIC.refreshTokenCanary,
+  SYNTHETIC.authorizationCode,
+  SYNTHETIC.state,
+  SYNTHETIC.codeVerifier,
+];
+
+async function readOAuth(): Promise<DiscoveryOAuth | null> {
+  const res = await driver.get('/.well-known/openwop');
+  return capabilityFamily<DiscoveryOAuth>(res.json, 'oauth') ?? null;
+}
+
+describe('oauth-authorization-code-roundtrip: the grant dance (RFC 0047 §C)', () => {
+  it('acquires a token via authorization_code and returns a reference, never the token', async () => {
+    const oauth = await readOAuth();
+    if (!oauth?.supported) return; // capability-gated
+    if (!Array.isArray(oauth.grants) || !oauth.grants.includes('authorization_code')) return; // grant-gated
+
+    // Seam contract: the host performs the full authorization-code roundtrip
+    // against the synthetic provider's authUrl/tokenUrl, persists the acquired
+    // token as a host.credentials entry, and returns the run-observable surfaces
+    // (events incl. connector.authorized + snapshot + any debug bundle) plus the
+    // resulting credentialRef.
+    const res = await driver.post('/v1/host/sample/oauth/authorize-code-roundtrip', {
+      provider: SYNTHETIC.provider,
+      authUrl: SYNTHETIC.authUrl,
+      tokenUrl: SYNTHETIC.tokenUrl,
+      scopes: SYNTHETIC.scopes,
+      authorizationCode: SYNTHETIC.authorizationCode,
+      state: SYNTHETIC.state,
+      redirectUri: SYNTHETIC.redirectUri,
+      codeVerifier: SYNTHETIC.codeVerifier,
+      accessTokenCanary: SYNTHETIC.accessTokenCanary,
+      refreshTokenCanary: SYNTHETIC.refreshTokenCanary,
+    });
+    // A host that hasn't wired the seam soft-skips (Tier-2, host-pending).
+    if (res.status === 404) return;
+
+    expect(
+      res.status,
+      driver.describe(
+        'RFC 0047 §C',
+        'the authorize-code-roundtrip seam MUST perform the authorization_code grant against the synthetic provider and return the run observable surfaces',
+      ),
+    ).toBeLessThan(400);
+
+    const body = (res.json ?? {}) as { credentialRef?: unknown };
+    expect(
+      typeof body.credentialRef === 'string' && body.credentialRef.length > 0,
+      driver.describe(
+        'RFC 0047 §C',
+        'a successful roundtrip MUST resolve to a credential REFERENCE (token persisted as a host.credentials entry), not the raw token',
+      ),
+    ).toBe(true);
+
+    // §C + §C.2 — no secret material anywhere in the observable response.
+    const serialized = JSON.stringify(res.json ?? {});
+    for (const secret of SECRET_VALUES) {
+      expect(
+        serialized.includes(secret),
+        driver.describe(
+          'RFC 0047 §C / SECURITY/invariants.yaml credential-payload-redaction',
+          `the authorization code, state, PKCE verifier, and acquired token material MUST NOT appear on any run-visible surface — leaked: ${secret.slice(0, 16)}…`,
+        ),
+      ).toBe(false);
+    }
+
+    // §C — connector.authorized carries the reference + scopes, never the token.
+    const events = (res.json as { events?: Array<{ type?: string; payload?: Record<string, unknown> }> })?.events;
+    if (Array.isArray(events)) {
+      const authorized = events.find((e) => e?.type === 'connector.authorized');
+      if (authorized?.payload) {
+        const keys = Object.keys(authorized.payload);
+        expect(
+          keys.includes('credentialRef') && !keys.includes('access_token') && !keys.includes('refresh_token'),
+          driver.describe(
+            'RFC 0047 §C',
+            'connector.authorized MUST carry { provider, credentialRef, scopes } and MUST NOT carry token material',
+          ),
+        ).toBe(true);
+      }
+    }
+  });
+});

package/src/scenarios/org-position-no-authority-escalation.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Org position confers no authority — the §B invariant, behavioral leg
+ * (RFC 0087 §B) — the protocol-tier `org-position-no-authority-escalation`.
+ *
+ * The STRUCTURAL leg (the `agent-org-chart.schema.json` is `additionalProperties:
+ * false` and rejects an authority-bearing field on a member) is always-on /
+ * server-free in `agent-org-chart-shape.test.ts`. This scenario is the
+ * BEHAVIORAL leg, gated on `capabilities.agents.orgChart.supported`: it proves
+ * against the LIVE host that the org-chart projector strips position-as-authority
+ * — no member, department, or responsibility-view object served on the wire
+ * carries an authority-bearing field (`scopes` / `canDispatch` / `permissions` /
+ * `authority` / `roleGrants` / `capabilities`), at every install scope. An org
+ * edge is an *ownership + reporting* record, never an authority grant.
+ *
+ * Soft-skips when unadvertised (default) / hard-fails under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true`.
+ *
+ * The deeper authority-invariance legs — a manager agent cannot dispatch a
+ * report's tools (RFC 0002 §A14), an RFC 0049 authorization decision is
+ * invariant to org position, an RFC 0051 approval gate is not satisfied by org
+ * seniority — require a non-normative host authorization-decide hook to force
+ * black-box; a conformant host need not expose one, so (mirroring the RFC 0070
+ * `agent-manifest-runtime` confidence-escalation note) they stay reference-impl
+ * tier and are NOT asserted here. The wire-projection proof below is the
+ * load-bearing, hook-free behavioral guarantee.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/agent-org-chart.md (§B)
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0087-agent-org-chart.md (§B)
+ *   - https://github.com/openwop/openwop/blob/main/SECURITY/invariants.yaml (org-position-no-authority-escalation)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readOrgChartCap, getOrgChart, getDepartmentView, AUTHORITY_FIELDS } from '../lib/agentOrgChart.js';
+
+/** Assert an org-chart wire object carries no authority-bearing field. */
+function expectNoAuthority(obj: Record<string, unknown> | undefined, where: string): void {
+  if (!obj || typeof obj !== 'object') return;
+  for (const f of AUTHORITY_FIELDS) {
+    expect(
+      !(f in obj),
+      driver.describe('RFC 0087 §B / org-position-no-authority-escalation', `${where} MUST NOT carry the authority field "${f}" — org position confers no authority`),
+    ).toBe(true);
+  }
+}
+
+describe('org-position-no-authority-escalation (RFC 0087 §B, behavioral)', () => {
+  it('the live org-chart wire carries no authority-bearing field on any member/department/view', async () => {
+    const cap = await readOrgChartCap();
+    if (!behaviorGate('openwop-org-position-no-authority', cap?.supported === true)) return;
+
+    const chart = await getOrgChart();
+    if (chart === null) return; // advertised but read not served yet — soft-skip
+
+    for (const m of chart.members ?? []) {
+      expectNoAuthority(m as Record<string, unknown>, 'an org-chart member');
+    }
+    for (const d of chart.departments ?? []) {
+      expectNoAuthority(d as Record<string, unknown>, 'an org-chart department');
+    }
+
+    // The §D responsibility roll-up is a portfolio union (workflow ids), never an
+    // authority grant — assert its members + the view object are authority-free too.
+    const probeDeptId = (chart.departments ?? [])[0]?.departmentId;
+    if (typeof probeDeptId === 'string') {
+      const { status, view } = await getDepartmentView(probeDeptId);
+      if (status === 200 && view) {
+        expectNoAuthority(view as unknown as Record<string, unknown>, 'the responsibility view');
+        expectNoAuthority(view.department as Record<string, unknown> | undefined, "the responsibility view's department");
+        for (const m of view.members ?? []) {
+          expectNoAuthority(m as Record<string, unknown>, 'a responsibility-view member');
+        }
+      }
+    }
+  });
+});

package/src/scenarios/runtime-requires-install-gate.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Pack runtime-requirements install gate — `registry-operations.md`
+ * §"Runtime-requirement install gate" + `node-packs.md` §"Runtime platform
+ * requirements" (RFC 0076 §A).
+ *
+ * Seam-gated behavioral scenarios for the install-time gate. A sandbox host MUST
+ * evaluate a pack's `runtime.requires[]` against the primitives it will grant
+ * and refuse install (`pack_runtime_requirement_unmet`) for any it won't grant —
+ * rather than silently installing and failing at first invocation (the
+ * `node:dns/promises` trial-load failure that motivated RFC 0076). A non-gating
+ * host SHOULD instead project `runtime.requires[]` onto the pack's inventory
+ * entry for operator visibility.
+ *
+ *   1. install-grant — requires ⊆ grant-set ⇒ install succeeds.
+ *   2. install-refuse — a required primitive the host won't grant ⇒
+ *      `pack_runtime_requirement_unmet { unmet, manifest, advice? }`, reusing the
+ *      `capability_not_provided` envelope shape.
+ *   3. non-sandbox projection — a host that does NOT gate platform access
+ *      installs and projects the declared requires[] for visibility (the §A SHOULD).
+ *
+ * All three drive `POST /v1/host/sample/packs/install-gate` and soft-skip when
+ * the host doesn't wire the seam (404). Behavior grade is `host-pending` until a
+ * runtime-requires-gating host (MyndHyve is the first adopter) lights it up.
+ *
+ * @see spec/v1/registry-operations.md §"Runtime-requirement install gate"
+ * @see spec/v1/host-sample-test-seams.md §"Open seams"
+ * @see RFCS/0076-pack-runtime-requirements-and-host-safe-fetch.md §A
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { installGate } from '../lib/runtimeRequires.js';
+
+function manifest(requires: string[]) {
+  return {
+    name: 'vendor.example.http',
+    version: '1.0.0',
+    engines: { openwop: '>=1.1 <2.0.0' },
+    runtime: { language: 'javascript', entry: 'index.mjs', requires },
+    nodes: [{ typeId: 'vendor.example.http.fetch', version: '1.0.0', category: 'integration', role: 'side-effect' }],
+  };
+}
+
+describe('runtime-requires install gate (RFC 0076 §A)', () => {
+  it('install-grant: requires ⊆ grant-set ⇒ install succeeds', async () => {
+    const res = await installGate({ manifest: manifest(['net.dns']), grantSet: ['net.dns', 'net.outbound'] });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      res.status,
+      driver.describe('registry-operations.md §"Runtime-requirement install gate"', 'a pack whose runtime.requires are all grantable MUST install (no refusal)'),
+    ).toBe(200);
+    expect(
+      res.body.outcome,
+      driver.describe('registry-operations.md §"Runtime-requirement install gate"', 'a granted install reports outcome:"installed"'),
+    ).toBe('installed');
+  });
+
+  it('install-refuse: an ungrantable primitive ⇒ pack_runtime_requirement_unmet', async () => {
+    const res = await installGate({ manifest: manifest(['net.dns']), grantSet: [] });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      res.status,
+      driver.describe('registry-operations.md §"Runtime-requirement install gate"', 'a pack requiring an ungranted primitive MUST be refused at install (not at first invocation)'),
+    ).toBe(400);
+    expect(
+      res.body.error,
+      driver.describe('registry-operations.md §"Runtime-requirement install gate"', 'the refusal MUST carry error code pack_runtime_requirement_unmet'),
+    ).toBe('pack_runtime_requirement_unmet');
+    expect(
+      Array.isArray(res.body.unmet) && (res.body.unmet as unknown[]).includes('net.dns'),
+      driver.describe('registry-operations.md §"Runtime-requirement install gate"', 'unmet[] MUST list the ungranted primitive(s) (capability_not_provided envelope)'),
+    ).toBe(true);
+    expect(
+      typeof res.body.manifest === 'string' && (res.body.manifest as string).includes('vendor.example.http'),
+      driver.describe('registry-operations.md §"Runtime-requirement install gate"', 'the refusal MUST name the offending manifest (name@version)'),
+    ).toBe(true);
+  });
+
+  it('non-sandbox projection: a non-gating host installs and projects requires[] (§A SHOULD)', async () => {
+    const res = await installGate({ manifest: manifest(['net.dns', 'net.outbound']), gating: false });
+    if (res === null) return; // seam absent — soft-skip
+    // A non-gating host installs unconditionally; the SHOULD is the projection.
+    // If the host gates anyway (returns 400) the projection SHOULD does not apply — tolerate either install shape.
+    if (res.status !== 200) return;
+    if (res.body.requiresProjected === undefined) return; // SHOULD, not MUST — a non-projecting host is conformant
+    const projected = res.body.requiresProjected as unknown;
+    expect(
+      Array.isArray(projected) && ['net.dns', 'net.outbound'].every((t) => (projected as unknown[]).includes(t)),
+      driver.describe('node-packs.md §"Runtime platform requirements"', 'a non-gating host that projects SHOULD surface the declared runtime.requires[] on the inventory entry verbatim'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/runtime-requires-shape.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Pack runtime-requirements vocabulary + shape — `node-packs.md`
+ * §"Runtime platform requirements" + `schemas/node-pack-manifest.schema.json`
+ * `$defs/Runtime.requires` (RFC 0076 §A).
+ *
+ * Server-free schema-validation scenario. The `runtime.requires[]` field is an
+ * OPTIONAL, closed, runtime-agnostic vocabulary a pack uses to declare the
+ * platform primitives its code exercises, so a sandbox host can gate at install
+ * time instead of trial-load. This file exercises the schema layer (the §A
+ * "vocabulary-validation" normative behavior — a raw builtin name is rejected —
+ * plus the additive/empty-array shape contract):
+ *
+ *   1. Positive: a manifest declaring valid primitives validates cleanly.
+ *   2. Positive: the field is OPTIONAL — a manifest omitting it validates.
+ *   3. Positive: an empty array (`requires: []`) validates and is equivalent to
+ *      omission (no host may read a distinct meaning into it; §A).
+ *   4. Positive: every one of the 8 vocabulary tokens individually validates.
+ *   5. Negative — raw builtin name: `"node:dns/promises"` (the value that
+ *      motivated the abstract vocabulary) is rejected; the registry/host
+ *      surfaces this as `invalid_manifest`.
+ *   6. Negative — duplicate token: `uniqueItems` is enforced.
+ *
+ * The install-time GATE behavior (grant / refuse → `pack_runtime_requirement_unmet`,
+ * and the non-sandbox-host SHOULD-projection) is host behavior and lives in the
+ * seam-gated `runtime-requires-install-gate.test.ts`.
+ *
+ * @see spec/v1/node-packs.md §"Runtime platform requirements"
+ * @see spec/v1/registry-operations.md §"Runtime-requirement install gate"
+ * @see schemas/node-pack-manifest.schema.json
+ * @see RFCS/0076-pack-runtime-requirements-and-host-safe-fetch.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import type { ErrorObject, ValidateFunction } from 'ajv';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const SCHEMA_PATH = join(SCHEMAS_DIR, 'node-pack-manifest.schema.json');
+
+const VOCABULARY = [
+  'net.dns',
+  'net.outbound',
+  'crypto',
+  'subprocess',
+  'fs.read',
+  'fs.write',
+  'env.read',
+  'clock',
+] as const;
+
+function manifest(requires?: unknown) {
+  const runtime: Record<string, unknown> = { language: 'javascript', entry: 'index.mjs' };
+  if (requires !== undefined) runtime.requires = requires;
+  return {
+    name: 'vendor.example.http',
+    version: '1.0.0',
+    engines: { openwop: '>=1.1 <2.0.0' },
+    runtime,
+    nodes: [{ typeId: 'vendor.example.http.fetch', version: '1.0.0', category: 'integration', role: 'side-effect' }],
+  };
+}
+
+describe('category: runtime.requires vocabulary + shape (RFC 0076 §A)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  // Register every schema first so cross-$refs resolve (node-pack-manifest
+  // references agent-manifest.schema.json for its agents[] branch). addSchema
+  // registers without compiling; the target compiles below.
+  for (const file of readdirSync(SCHEMAS_DIR)) {
+    if (!file.endsWith('.schema.json')) continue;
+    try {
+      ajv.addSchema(JSON.parse(readFileSync(join(SCHEMAS_DIR, file), 'utf8')) as Record<string, unknown>);
+    } catch {
+      /* duplicate/already-registered — the target is compiled below */
+    }
+  }
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+  const validate = (ajv.getSchema(schema['$id'] as string) ?? ajv.compile(schema)) as ValidateFunction;
+
+  const errorsOn = (m: unknown): ErrorObject[] => {
+    expect(validate(m)).toBe(false);
+    return validate.errors ?? [];
+  };
+
+  it('positive: a manifest declaring valid primitives validates cleanly', () => {
+    const ok = validate(manifest(['net.dns', 'net.outbound']));
+    expect(
+      ok,
+      `node-packs.md §"Runtime platform requirements": a well-formed runtime.requires MUST validate. Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('positive: runtime.requires is OPTIONAL — a manifest omitting it validates (additive)', () => {
+    expect(
+      validate(manifest(undefined)),
+      'node-pack-manifest.schema.json: runtime.requires is additive/OPTIONAL — packs predating RFC 0076 validate unchanged',
+    ).toBe(true);
+  });
+
+  it('positive: an empty requires[] validates (equivalent to omission per §A)', () => {
+    expect(
+      validate(manifest([])),
+      'node-packs.md §"Runtime platform requirements": runtime.requires:[] is valid and equivalent to omission',
+    ).toBe(true);
+  });
+
+  it('positive: every vocabulary token individually validates', () => {
+    for (const token of VOCABULARY) {
+      expect(
+        validate(manifest([token])),
+        `node-pack-manifest.schema.json: "${token}" is in the RFC 0076 §A vocabulary. Errors: ${JSON.stringify(validate.errors)}`,
+      ).toBe(true);
+    }
+  });
+
+  it('negative: a raw builtin name (node:dns/promises) is rejected (→ invalid_manifest)', () => {
+    const errs = errorsOn(manifest(['node:dns/promises']));
+    expect(
+      errs.some((e) => e.instancePath.includes('/runtime/requires')),
+      'node-packs.md §"Runtime platform requirements": raw language builtin names are NOT in the closed vocabulary — the abstract net.dns is the portable equivalent; the registry/host surfaces this as invalid_manifest',
+    ).toBe(true);
+  });
+
+  it('negative: a duplicate token is rejected (uniqueItems)', () => {
+    const errs = errorsOn(manifest(['net.dns', 'net.dns']));
+    expect(
+      errs.some((e) => e.keyword === 'uniqueItems'),
+      'node-pack-manifest.schema.json: runtime.requires has uniqueItems:true',
+    ).toBe(true);
+  });
+});

package/src/scenarios/safefetch-behavior.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Host-provided safe-fetch behavior — `host-capabilities.md` §host.http
+ * (`ctx.http.safeFetch`) + RFC 0076 §B.
+ *
+ * Seam-gated behavioral scenarios for the pack-facing `ctx.http.safeFetch`. When
+ * a host advertises `capabilities.httpClient.safeFetch.supported`, the
+ * host-mediated fetch MUST apply the §host.http SSRF guard (resolve→pin→connect)
+ * so a pack can do outbound HTTP without reaching for `node:dns` / raw sockets:
+ *
+ *   1. SSRF block — a loopback / RFC 1918 / cloud-metadata target ⇒
+ *      `{ outcome: "blocked", blocked: "ssrf" }`; the host MUST NOT connect.
+ *   2. DNS-rebinding — a public name re-resolving to a blocked address
+ *      (`simulateRebindTo`) ⇒ also blocked (the resolved IP is pinned).
+ *   3. Connection-upgrade refusal — `Connection: upgrade` ⇒
+ *      `{ outcome: "blocked", blocked: "upgrade" }` (no 101 socket-hijack escape).
+ *   4. Audit-when-both — when `toolHooks.prePostEvents` is also advertised, a
+ *      fetched call emits the `agent.toolCalled` / `agent.toolReturned` pair
+ *      (`transport: "http"`).
+ *
+ * All drive `POST /v1/host/sample/http/safe-fetch` and soft-skip when the host
+ * doesn't advertise `safeFetch` or doesn't wire the seam (404). Behavior grade
+ * is `host-pending` until a `safeFetch` host lights it up. The SSRF *guarantee*
+ * reuses the `http-client-ssrf-guard` SECURITY invariant — no new invariant.
+ *
+ * @see spec/v1/host-capabilities.md §host.http
+ * @see spec/v1/host-sample-test-seams.md §"Open seams"
+ * @see RFCS/0076-pack-runtime-requirements-and-host-safe-fetch.md §B
+ * @see SECURITY/invariants.yaml id: http-client-ssrf-guard
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isSafeFetchSupported, isToolHookAuditOn, safeFetch } from '../lib/safeFetch.js';
+
+describe('safefetch-behavior (RFC 0076 §B / §host.http)', () => {
+  it('blocks a metadata-endpoint target (SSRF guard)', async () => {
+    if (!(await isSafeFetchSupported())) return; // capability absent — soft-skip
+    const res = await safeFetch({ url: 'http://169.254.169.254/latest/meta-data/' });
+    if (res === null) return; // seam absent — soft-skip
+    expect(
+      res.outcome,
+      driver.describe('host-capabilities.md §host.http', 'safeFetch MUST NOT connect to a cloud-metadata address'),
+    ).toBe('blocked');
+    expect(
+      res.blocked,
+      driver.describe('host-capabilities.md §host.http', 'a blocked SSRF target reports blocked:"ssrf" (http-client-ssrf-guard invariant)'),
+    ).toBe('ssrf');
+  });
+
+  it('blocks a loopback target (SSRF guard)', async () => {
+    if (!(await isSafeFetchSupported())) return;
+    const res = await safeFetch({ url: 'http://127.0.0.1:6379/' });
+    if (res === null) return;
+    expect(
+      res.outcome,
+      driver.describe('host-capabilities.md §host.http', 'safeFetch MUST NOT connect to loopback'),
+    ).toBe('blocked');
+  });
+
+  it('blocks DNS-rebinding (resolved IP is pinned for the connection)', async () => {
+    if (!(await isSafeFetchSupported())) return;
+    const res = await safeFetch({ url: 'http://example.com/', simulateRebindTo: '169.254.169.254' });
+    if (res === null) return;
+    expect(
+      res.outcome,
+      driver.describe('host-capabilities.md §host.http', 'a public name that re-resolves to a blocked address MUST be blocked (rebinding defeat)'),
+    ).toBe('blocked');
+  });
+
+  it('refuses a Connection: upgrade request (no 101 socket-hijack escape)', async () => {
+    if (!(await isSafeFetchSupported())) return;
+    const res = await safeFetch({ url: 'https://example.com/', init: { headers: { Connection: 'upgrade' } } });
+    if (res === null) return;
+    expect(
+      res.outcome,
+      driver.describe('host-capabilities.md §host.http', 'safeFetch MUST refuse a connection-upgrade attempt'),
+    ).toBe('blocked');
+    expect(
+      res.blocked,
+      driver.describe('host-capabilities.md §host.http', 'a refused upgrade reports blocked:"upgrade"'),
+    ).toBe('upgrade');
+  });
+
+  it('emits the tool-hooks audit pair when prePostEvents is also advertised', async () => {
+    if (!(await isSafeFetchSupported())) return;
+    if (!(await isToolHookAuditOn())) return; // audit MUST applies only when both advertised
+    const res = await safeFetch({ url: 'https://example.com/' });
+    if (res === null) return;
+    if (res.outcome !== 'fetched') return; // only a completed call carries the pair
+    expect(
+      res.toolCalled !== undefined && res.toolReturned !== undefined,
+      driver.describe('host-capabilities.md §host.http', 'when toolHooks.prePostEvents + safeFetch are both advertised, a safeFetch call MUST emit the agent.toolCalled/agent.toolReturned pair'),
+    ).toBe(true);
+    expect(
+      (res.toolCalled as { transport?: string } | undefined)?.transport,
+      driver.describe('host-capabilities.md §host.http', 'the audit pair carries transport:"http"'),
+    ).toBe('http');
+  });
+});