@openwop/openwop-conformance 1.5.0 → 1.6.1

package/src/scenarios/authorization-fail-closed.test.ts

@@ -0,0 +1,80 @@
+/**
+ * authorization-fail-closed — RFC 0049 §C invariant verification.
+ *
+ * Status: DRAFT. RFC 0049 (RBAC scopes & authorization decisions) is `Draft`.
+ * Backs the SECURITY invariant `authorization-fail-closed`.
+ *
+ * Capability-gated: skips when the host does not advertise
+ * `capabilities.authorization.supported = true`.
+ *
+ * What this scenario asserts:
+ *   1. Advertisement shape — when authorization is supported, `failClosed`
+ *      (when present) is exactly `true` (RFC 0049 §C).
+ *   2. Fail-closed MUST-NOT — when the host exposes the optional
+ *      `POST /v1/host/sample/authorization/decide` test seam, a decision for
+ *      a principal with an absent/unseeded role MUST resolve to
+ *      `allowed: false`. The host MUST NOT default-allow under any error
+ *      condition.
+ *
+ * Hosts without the seam soft-skip the behavioral probe (404).
+ *
+ * @see RFCS/0049-rbac-scopes-and-authorization-decisions.md
+ * @see SECURITY/invariants.yaml id: authorization-fail-closed
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryAuthorization {
+  supported?: boolean;
+  failClosed?: boolean;
+}
+
+interface DiscoveryDoc {
+  capabilities?: {
+    authorization?: DiscoveryAuthorization;
+  };
+}
+
+async function readAuthorization(): Promise<DiscoveryAuthorization | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.authorization ?? null;
+}
+
+describe('authorization-fail-closed: advertisement shape (RFC 0049 §C)', () => {
+  it('failClosed is exactly true when authorization is supported', async () => {
+    const authz = await readAuthorization();
+    if (!authz?.supported || authz.failClosed === undefined) return;
+    expect(
+      authz.failClosed,
+      driver.describe('RFC 0049 §C', 'capabilities.authorization.failClosed MUST be `true`'),
+    ).toBe(true);
+  });
+});
+
+describe('authorization-fail-closed: absent/unseeded role MUST deny (RFC 0049 §C)', () => {
+  it('a decision for an unseeded-role principal resolves allowed=false', async () => {
+    const authz = await readAuthorization();
+    if (!authz?.supported) return; // capability-gated
+
+    // Seam contract: request an authorization decision for a principal whose
+    // role is absent/unseeded. The host MUST fail closed.
+    const res = await driver.post('/v1/host/sample/authorization/decide', {
+      principal: 'conformance-unseeded-principal',
+      action: 'runs:cancel',
+      resource: 'run-conformance-probe',
+    });
+    // 404 from a host that hasn't wired the seam is a soft-skip.
+    if (res.status === 404) return;
+
+    const decision = res.json as { allowed?: boolean } | undefined;
+    expect(
+      decision?.allowed,
+      driver.describe(
+        'SECURITY/invariants.yaml authorization-fail-closed',
+        'an absent/unseeded role MUST deny (allowed=false); the host MUST NOT default-allow',
+      ),
+    ).toBe(false);
+  });
+});

package/src/scenarios/authorization-roles-shape.test.ts

@@ -0,0 +1,83 @@
+/**
+ * authorization-roles-shape — RFC 0049 §A advertisement-shape verification.
+ *
+ * Status: DRAFT. RFC 0049 (RBAC scopes & authorization decisions) is `Draft`.
+ * The `capabilities.authorization` block has landed in
+ * `schemas/capabilities.schema.json`.
+ *
+ * Always runs (shape-only): when the host advertises
+ * `capabilities.authorization`, its fields MUST be well-formed.
+ *
+ * What this scenario asserts:
+ *   1. `capabilities.authorization` is either absent or a well-formed object.
+ *   2. When `supported: true`: `failClosed` (when present) is exactly `true`
+ *      (RFC 0049 §C), and every `roles[]` entry has a non-empty `role` + a
+ *      `scopes` array (RFC 0049 §A).
+ *
+ * @see RFCS/0049-rbac-scopes-and-authorization-decisions.md
+ * @see spec/v1/auth.md §"Role-based authorization (RFC 0049)"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryRole {
+  role?: string;
+  scopes?: string[];
+}
+
+interface DiscoveryAuthorization {
+  supported?: boolean;
+  failClosed?: boolean;
+  roles?: DiscoveryRole[];
+}
+
+interface DiscoveryDoc {
+  capabilities?: {
+    authorization?: DiscoveryAuthorization;
+  };
+}
+
+async function readAuthorization(): Promise<DiscoveryAuthorization | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.authorization ?? null;
+}
+
+describe('authorization-roles-shape: advertisement shape (RFC 0049 §A)', () => {
+  it('capabilities.authorization is either absent or well-formed', async () => {
+    const authz = await readAuthorization();
+    if (authz === null) return; // host doesn't advertise authorization at all
+    expect(
+      typeof authz.supported,
+      driver.describe(
+        'capabilities.schema.json §authorization',
+        'capabilities.authorization.supported MUST be a boolean when authorization is advertised',
+      ),
+    ).toBe('boolean');
+  });
+
+  it('failClosed, when present, is exactly true (RFC 0049 §C)', async () => {
+    const authz = await readAuthorization();
+    if (!authz?.supported || authz.failClosed === undefined) return;
+    expect(
+      authz.failClosed,
+      driver.describe('RFC 0049 §C', 'capabilities.authorization.failClosed MUST be `true` (fail-closed)'),
+    ).toBe(true);
+  });
+
+  it('every advertised role has a non-empty role name + a scopes array', async () => {
+    const authz = await readAuthorization();
+    if (!authz?.supported || authz.roles === undefined) return;
+    for (const entry of authz.roles) {
+      expect(
+        typeof entry.role === 'string' && entry.role.length > 0,
+        driver.describe('RFC 0049 §A', 'each capabilities.authorization.roles[] entry MUST declare a non-empty role'),
+      ).toBe(true);
+      expect(
+        Array.isArray(entry.scopes),
+        driver.describe('RFC 0049 §A', 'each role MUST declare a scopes array'),
+      ).toBe(true);
+    }
+  });
+});

package/src/scenarios/connector-manifest-validity.test.ts

@@ -0,0 +1,142 @@
+/**
+ * connector-manifest-validity — RFC 0045 §A/§B verification.
+ *
+ * Status: DRAFT. RFC 0045 (connector pack manifest & action model) is `Draft`.
+ * The optional `connector` block + `Connector` / `ConnectorAuth` $defs have
+ * landed in `schemas/node-pack-manifest.schema.json`.
+ *
+ * Server-free schema + semantic validation. Two contracts:
+ *   1. Schema validity (§A): a well-formed `connector` block validates; a
+ *      block missing `id`/`displayName` or an action missing `typeId` is
+ *      rejected. Both ConnectorAuth variants (oauth2 / credential) validate.
+ *   2. Action resolution (§B): every `connector.actions[].typeId` and
+ *      `connector.triggers[]` entry MUST resolve to a `nodes[].typeId` in the
+ *      same manifest; an unresolved reference is `connector_action_unresolved`.
+ *
+ * The Connector subschema is extracted self-contained (Connector + its
+ * ConnectorAuth + NodeAuth $defs) so ajv compiles it without resolving the
+ * parent manifest's external `agent-manifest.schema.json` $ref.
+ *
+ * @see RFCS/0045-connector-pack-manifest-action-model.md
+ * @see schemas/node-pack-manifest.schema.json §Connector
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+interface SchemaDefs {
+  $defs: Record<string, unknown>;
+  $schema: string;
+}
+
+const manifestSchema = JSON.parse(
+  readFileSync(join(SCHEMAS_DIR, 'node-pack-manifest.schema.json'), 'utf8'),
+) as SchemaDefs;
+
+// Self-contained Connector schema: root = Connector, carrying the $defs it
+// references (ConnectorAuth → NodeAuth). No external $ref resolution needed.
+const connectorSchema = {
+  $schema: manifestSchema.$schema,
+  ...(manifestSchema.$defs.Connector as Record<string, unknown>),
+  $defs: {
+    ConnectorAuth: manifestSchema.$defs.ConnectorAuth,
+    NodeAuth: manifestSchema.$defs.NodeAuth,
+  },
+};
+
+// §B action/trigger resolution — the semantic check the registry applies
+// beyond pure JSON Schema (typeIds must resolve to real nodes).
+interface ConnectorAction {
+  typeId: string;
+}
+interface ConnectorBlock {
+  actions?: ConnectorAction[];
+  triggers?: string[];
+}
+function unresolvedReferences(nodeTypeIds: string[], connector: ConnectorBlock): string[] {
+  const known = new Set(nodeTypeIds);
+  const refs = [
+    ...(connector.actions ?? []).map((a) => a.typeId),
+    ...(connector.triggers ?? []),
+  ];
+  return refs.filter((t) => !known.has(t));
+}
+
+describe('category: connector-manifest validity — schema shape (RFC 0045 §A)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(connectorSchema);
+
+  it('positive: a well-formed connector block (oauth2 auth) validates', () => {
+    const ok = validate({
+      id: 'salesforce',
+      displayName: 'Salesforce',
+      auth: { type: 'oauth2', provider: 'salesforce', scopes: ['api'] },
+      actions: [
+        { typeId: 'vendor.acme.salesforce.upsert', displayName: 'Upsert', idempotent: true, rateLimit: { requests: 100, perSeconds: 60 } },
+        { typeId: 'vendor.acme.salesforce.query', displayName: 'Query', paginated: true },
+      ],
+      triggers: ['vendor.acme.salesforce.onRecordChange'],
+    });
+    expect(ok, JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it('positive: credential-auth variant validates', () => {
+    const ok = validate({
+      id: 'stripe',
+      displayName: 'Stripe',
+      auth: { type: 'credential', key: 'stripe-secret-key', scope: 'workspace' },
+      actions: [{ typeId: 'vendor.acme.stripe.charge', displayName: 'Charge' }],
+    });
+    expect(ok, JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it('negative: connector missing displayName is rejected', () => {
+    expect(validate({ id: 'salesforce' })).toBe(false);
+  });
+
+  it('negative: an action missing typeId is rejected', () => {
+    const ok = validate({
+      id: 'salesforce',
+      displayName: 'Salesforce',
+      actions: [{ displayName: 'Upsert' }],
+    });
+    expect(ok).toBe(false);
+  });
+
+  it('negative: an unknown ConnectorAuth type is rejected', () => {
+    const ok = validate({
+      id: 'salesforce',
+      displayName: 'Salesforce',
+      auth: { type: 'basic', user: 'x' },
+    });
+    expect(ok).toBe(false);
+  });
+});
+
+describe('category: connector-manifest validity — action resolution (RFC 0045 §B)', () => {
+  const nodeTypeIds = [
+    'vendor.acme.salesforce.upsert',
+    'vendor.acme.salesforce.query',
+    'vendor.acme.salesforce.onRecordChange',
+  ];
+
+  it('all action + trigger typeIds resolve to nodes[] in the same manifest', () => {
+    const unresolved = unresolvedReferences(nodeTypeIds, {
+      actions: [{ typeId: 'vendor.acme.salesforce.upsert' }, { typeId: 'vendor.acme.salesforce.query' }],
+      triggers: ['vendor.acme.salesforce.onRecordChange'],
+    });
+    expect(unresolved, 'every connector.actions[].typeId + triggers[] MUST resolve to a nodes[].typeId').toEqual([]);
+  });
+
+  it('an action typeId not in nodes[] is flagged (connector_action_unresolved)', () => {
+    const unresolved = unresolvedReferences(nodeTypeIds, {
+      actions: [{ typeId: 'vendor.acme.salesforce.does-not-exist' }],
+    });
+    expect(unresolved).toContain('vendor.acme.salesforce.does-not-exist');
+  });
+});

package/src/scenarios/credential-payload-redaction.test.ts

@@ -0,0 +1,93 @@
+/**
+ * credential-payload-redaction — RFC 0046 §C.1 / §E invariant verification.
+ *
+ * Status: DRAFT. RFC 0046 (`host.credentials`) is `Draft`. Backs the
+ * SECURITY invariant `credential-payload-redaction`.
+ *
+ * Capability-gated: skips when the host does not advertise
+ * `capabilities.credentials.supported = true`.
+ *
+ * What this scenario asserts:
+ *   1. Advertisement shape — `capabilities.credentials` is well-formed when
+ *      supported (delegated in detail to credentials-capability-shape).
+ *   2. Redaction MUST-NOT — when the host exposes the optional
+ *      `POST /v1/host/sample/credentials/echo` test seam, resolving a seeded
+ *      credential whose plaintext is a known canary MUST NOT cause that
+ *      canary to appear in ANY of the run's observable surfaces (events,
+ *      inputs, persisted variables, channels, snapshot, debug bundle). The
+ *      reference is the only credential artifact permitted on the wire.
+ *
+ * Hosts without the test seam soft-skip the redaction probe (404) and still
+ * assert the advertisement shape — mirroring fs-path-traversal.
+ *
+ * @see RFCS/0046-host-credentials-capability.md
+ * @see SECURITY/invariants.yaml id: credential-payload-redaction
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryCredentials {
+  supported?: boolean;
+}
+
+interface DiscoveryDoc {
+  capabilities?: {
+    credentials?: DiscoveryCredentials;
+  };
+}
+
+// A unique canary the seam seeds as the resolved credential's plaintext.
+const CANARY = 'OPENWOP_CRED_CANARY_4f1c8a2e9b';
+
+async function readCredentials(): Promise<DiscoveryCredentials | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.credentials ?? null;
+}
+
+describe('credential-payload-redaction: advertisement shape (RFC 0046 §A)', () => {
+  it('capabilities.credentials.supported is a boolean when advertised', async () => {
+    const cred = await readCredentials();
+    if (cred === null) return;
+    expect(
+      typeof cred.supported,
+      driver.describe(
+        'capabilities.schema.json §credentials',
+        'capabilities.credentials.supported MUST be a boolean when credentials is advertised',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+describe('credential-payload-redaction: resolved material MUST NOT cross the wire (RFC 0046 §C.1)', () => {
+  it('canary plaintext is absent from every observable run surface', async () => {
+    const cred = await readCredentials();
+    if (!cred?.supported) return; // capability-gated
+
+    // Seam contract: resolve a seeded credential whose plaintext is CANARY,
+    // run an echo node, and return the run's observable surfaces.
+    const res = await driver.post('/v1/host/sample/credentials/echo', { canary: CANARY });
+    // 404 from a host that hasn't wired the test seam is a soft-skip.
+    if (res.status === 404) return;
+
+    expect(
+      res.status,
+      driver.describe(
+        'SECURITY/invariants.yaml credential-payload-redaction',
+        'the credentials echo seam MUST resolve the seeded credential and return its observable surfaces',
+      ),
+    ).toBeLessThan(400);
+
+    // The entire serialized observable surface (events + inputs + variables +
+    // channels + snapshot + debug bundle) MUST NOT contain the canary plaintext.
+    const serialized = JSON.stringify(res.json ?? {});
+    expect(
+      serialized.includes(CANARY),
+      driver.describe(
+        'SECURITY/invariants.yaml credential-payload-redaction',
+        'resolved credential material MUST NOT appear in inputs, variables, channels, events, snapshot, or debug bundle — only the reference may cross the wire',
+      ),
+    ).toBe(false);
+  });
+});

package/src/scenarios/credentials-capability-shape.test.ts

@@ -0,0 +1,90 @@
+/**
+ * credentials-capability-shape — RFC 0046 §A advertisement-shape verification.
+ *
+ * Status: DRAFT. RFC 0046 (`host.credentials`) is `Draft`. The
+ * `capabilities.credentials` block has landed in
+ * `schemas/capabilities.schema.json` and the invariant row
+ * `credential-payload-redaction` is in `SECURITY/invariants.yaml`.
+ *
+ * Always runs (shape-only): when the host advertises `capabilities.credentials`,
+ * its fields MUST be well-formed; when it doesn't, the block is simply absent.
+ *
+ * What this scenario asserts:
+ *   1. `capabilities.credentials` is either absent or a well-formed object.
+ *   2. When `supported: true`, `scopes` (when present) is a subset of
+ *      {user, workspace, tenant}, and `rotation` (when present) is one of
+ *      {none, two-key-overlap} (RFC 0046 §A).
+ *
+ * @see RFCS/0046-host-credentials-capability.md
+ * @see SECURITY/invariants.yaml id: credential-payload-redaction
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryCredentials {
+  supported?: boolean;
+  scopes?: string[];
+  encryptionAtRest?: boolean;
+  rotation?: string;
+  sharing?: boolean;
+}
+
+interface DiscoveryDoc {
+  capabilities?: {
+    credentials?: DiscoveryCredentials;
+  };
+}
+
+const VALID_SCOPES: ReadonlySet<string> = new Set(['user', 'workspace', 'tenant']);
+const VALID_ROTATION: ReadonlySet<string> = new Set(['none', 'two-key-overlap']);
+
+async function readCredentials(): Promise<DiscoveryCredentials | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.credentials ?? null;
+}
+
+describe('credentials-capability-shape: advertisement shape (RFC 0046 §A)', () => {
+  it('capabilities.credentials is either absent or well-formed', async () => {
+    const cred = await readCredentials();
+    if (cred === null) return; // host doesn't advertise host.credentials at all
+    expect(
+      typeof cred.supported,
+      driver.describe(
+        'capabilities.schema.json §credentials',
+        'capabilities.credentials.supported MUST be a boolean when credentials is advertised',
+      ),
+    ).toBe('boolean');
+  });
+
+  it('scopes is a subset of {user, workspace, tenant} when supported', async () => {
+    const cred = await readCredentials();
+    if (!cred?.supported || cred.scopes === undefined) return;
+    expect(
+      Array.isArray(cred.scopes),
+      driver.describe('RFC 0046 §A', 'capabilities.credentials.scopes MUST be an array'),
+    ).toBe(true);
+    for (const scope of cred.scopes) {
+      expect(
+        VALID_SCOPES.has(scope),
+        driver.describe(
+          'RFC 0046 §A',
+          `capabilities.credentials.scopes entries MUST be one of {${[...VALID_SCOPES].join(', ')}}, got: ${scope}`,
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it('rotation is one of {none, two-key-overlap} when present', async () => {
+    const cred = await readCredentials();
+    if (!cred?.supported || cred.rotation === undefined) return;
+    expect(
+      VALID_ROTATION.has(cred.rotation),
+      driver.describe(
+        'RFC 0046 §A',
+        `capabilities.credentials.rotation MUST be one of {${[...VALID_ROTATION].join(', ')}}, got: ${cred.rotation}`,
+      ),
+    ).toBe(true);
+  });
+});