@substrat-run/contract-tests 0.52.0 → 0.54.0

package/dist/scope-host-suite.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { connectorCalls, connectorTestFetch, resetConnectorCalls } from './connector-fixture.js';
-import { connectionId, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, } from '@substrat-run/contracts';
+import { connectionId, dataSubjectId, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, } from '@substrat-run/contracts';
 import { runPlatformSweep, ulid } from '@substrat-run/kernel';
 import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, testModManifest, victimModManifest, } from './modules.js';
 /**
@@ -536,6 +536,136 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 await expect(host.admin.exportScope(staff, t2, s1)).rejects.toThrow();
             });
         });
+        // -- subject erasure (#37, master-plan §5.3) ------------------------------
+        //
+        // `piiClass` has been enforced at the type level since the contracts package existed —
+        // an event carrying PII cannot be declared without a `subjectId`, because
+        // "crypto-shredding must be able to key the erasure". These are that erasure, and
+        // every adapter owes all of it.
+        //
+        // The mechanism splits the way the STORES split. Tier 1 is mutable, so erasing there
+        // is redaction: the payload goes, the envelope stays. A platform-retained COPY is not
+        // mutable — that is what a backup IS — so erasing there is cryptographic: the copy was
+        // sealed per-subject on the way out, and destroying that key reaches backwards into
+        // every copy already taken. Both halves are asserted here; what a dump looks like
+        // after each is `sealDump`/`openDump`'s job (control-plane-api).
+        describe('subject erasure (#37)', () => {
+            /** Every outbox row for one subject, read through the module's own projection. */
+            const spineFor = async (subject) => {
+                const stub = await host.getScope(alice, t1, s1);
+                const rows = (await stub.invoke('test/read-outbox', undefined));
+                return rows.filter((r) => r.subject_id === subject);
+            };
+            it('redacts the payload and KEEPS the envelope — and only for the named subject', async () => {
+                const alicia = dataSubjectId.parse(ulid());
+                const bruno = dataSubjectId.parse(ulid());
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/emit-event', { subject: alicia, secret: 'alicia-was-here' });
+                await stub.invoke('test/emit-event', { subject: bruno, secret: 'bruno-was-here' });
+                const before = await spineFor(alicia);
+                expect(before).toHaveLength(1);
+                expect(before[0].payload).toContain('alicia-was-here');
+                const receipt = await host.admin.shredSubject(staff, t1, s1, alicia);
+                expect(receipt.subjectId).toBe(alicia);
+                expect(receipt.eventsRedacted).toBe(1);
+                expect(receipt.tombstoned).toBe(true);
+                // The payload is gone. The ENVELOPE is not: master-plan §5.3 keeps the
+                // pseudonymous key and the transaction fact, so a timeline still shows that
+                // something happened, to what, and when — it no longer shows what was said.
+                const after = await spineFor(alicia);
+                expect(after).toHaveLength(1);
+                expect(after[0].payload).toBeNull();
+                expect(after[0].id).toBe(before[0].id);
+                expect(after[0].pii_class).toBe('pseudonymous');
+                expect(after[0].subject_id).toBe(alicia);
+                // The other subject is untouched — an erasure that over-reaches is its own bug.
+                const others = await spineFor(bruno);
+                expect(others[0].payload).toContain('bruno-was-here');
+            });
+            it('is idempotent — a re-run erases nothing and still reports the tombstone', async () => {
+                const subject = dataSubjectId.parse(ulid());
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/emit-event', { subject, secret: 'once' });
+                const first = await host.admin.shredSubject(staff, t1, s1, subject);
+                expect(first.eventsRedacted).toBe(1);
+                // A retry after a crash must converge rather than double-count or throw: the
+                // payloads are already null and the key is already destroyed.
+                const second = await host.admin.shredSubject(staff, t1, s1, subject);
+                expect(second.eventsRedacted).toBe(0);
+                expect(second.keyDestroyed).toBe(false);
+                expect(second.tombstoned).toBe(true);
+            });
+            it('seals and opens a payload under the subject who owns it', async () => {
+                const subject = dataSubjectId.parse(ulid());
+                const sealed = await host.admin.sealSubjectPayloads(staff, t1, s1, [
+                    { subjectId: subject, plaintext: '{"note":"only for them"}' },
+                ]);
+                expect(sealed[0]).not.toBeNull();
+                // Sealed means sealed: the plaintext is not sitting in the envelope.
+                expect(sealed[0].ciphertext).not.toContain('only for them');
+                const opened = await host.admin.openSubjectPayloads(staff, t1, s1, [
+                    { subjectId: subject, sealed: sealed[0] },
+                ]);
+                expect(opened[0]).toBe('{"note":"only for them"}');
+            });
+            it('after a shred: what was sealed no longer opens, and nothing may be re-sealed', async () => {
+                const subject = dataSubjectId.parse(ulid());
+                const [sealed] = await host.admin.sealSubjectPayloads(staff, t1, s1, [
+                    { subjectId: subject, plaintext: 'in the backup' },
+                ]);
+                await host.admin.shredSubject(staff, t1, s1, subject);
+                // THE property. The ciphertext is untouched — it is still sitting in whatever copy
+                // it was written to — and it is now permanently unreadable. This is the only
+                // mechanism that reaches into an immutable store, which is why it exists.
+                const opened = await host.admin.openSubjectPayloads(staff, t1, s1, [
+                    { subjectId: subject, sealed: sealed },
+                ]);
+                expect(opened[0]).toBeNull();
+                // And the tombstone holds: a LATER export must not mint this subject a fresh
+                // working key. Without this, the next backup would quietly undo the erasure.
+                const resealed = await host.admin.sealSubjectPayloads(staff, t1, s1, [
+                    { subjectId: subject, plaintext: 'in the backup' },
+                ]);
+                expect(resealed[0]).toBeNull();
+            });
+            it('leaves a different subject in the same scope fully readable', async () => {
+                const shredded = dataSubjectId.parse(ulid());
+                const spared = dataSubjectId.parse(ulid());
+                const [a, b] = await host.admin.sealSubjectPayloads(staff, t1, s1, [
+                    { subjectId: shredded, plaintext: 'theirs' },
+                    { subjectId: spared, plaintext: 'not theirs' },
+                ]);
+                await host.admin.shredSubject(staff, t1, s1, shredded);
+                const opened = await host.admin.openSubjectPayloads(staff, t1, s1, [
+                    { subjectId: shredded, sealed: a },
+                    { subjectId: spared, sealed: b },
+                ]);
+                // Per-subject keys, not a per-scope one: erasing a person must not cost the
+                // backup its ability to restore everyone else.
+                expect(opened[0]).toBeNull();
+                expect(opened[1]).toBe('not theirs');
+            });
+            it('fails closed on a mismatched (tenantId, scopeId) pair (K-3)', async () => {
+                const subject = dataSubjectId.parse(ulid());
+                // Naming another tenant's scope must not reach its keys — or erase in it.
+                await expect(host.admin.shredSubject(staff, t2, s1, subject)).rejects.toThrow();
+                await expect(host.admin.sealSubjectPayloads(staff, t2, s1, [{ subjectId: subject, plaintext: 'x' }])).rejects.toThrow();
+            });
+            it('records the erasure in BOTH logs — mutation and evidence-destruction', async () => {
+                const subject = dataSubjectId.parse(ulid());
+                await host.admin.shredSubject(staff, t1, s1, subject);
+                // The admin log because it is a mutation, carrying the receipt as `after`: an
+                // erasure that leaves no proof it ran cannot answer a DSAR.
+                const audit = await host.admin.auditLog(staff, { tenantId: t1 });
+                const entry = audit.filter((e) => e.action === 'shredSubject').at(-1);
+                expect(entry).toBeDefined();
+                expect(JSON.stringify(entry.after)).toContain(subject);
+                // The access log because it DESTROYS evidence — "who asked for this to
+                // disappear" is itself part of the record.
+                const access = await host.admin.accessLog(staff, { tenantId: t1, method: 'shredSubject' });
+                expect(access.length).toBeGreaterThan(0);
+            });
+        });
         // -- scope import: the fork round-trip (preview-and-snapshots.md §3) -------
         //
         // The write side of exportScope. `importScope` provisions a NEW scope and loads
@@ -1028,6 +1158,60 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             });
         });
         // -- the integrations hub: connections (#101) -----------------------------
+        // -- operational failures (#559): the durable record of what the platform could NOT do --
+        describe('operational failures (#559)', () => {
+            it('records a failure and finds it again — by reference, by vertical, newest first', async () => {
+                await host.admin.recordOpsFailure({
+                    actor: staff,
+                    operation: 'deploy.upload',
+                    stage: 'wfp-upload',
+                    tenantId: t1,
+                    vertical: 'acme/crm',
+                    status: 502,
+                    message: 'WfP upload failed (500): internal error; reference = testref123abc',
+                    reference: 'testref123abc',
+                });
+                await host.admin.recordOpsFailure({
+                    actor: staff,
+                    operation: 'POST /verticals/:slug/previews',
+                    vertical: 'acme/crm',
+                    status: 502,
+                    message: 'internal error; reference = otherref456',
+                    reference: 'otherref456',
+                });
+                // Newest first by default — an operator asks "what broke lately", and the
+                // adapter's ULIDs are monotonic, so creation order IS id order.
+                const recent = await host.admin.listOpsFailures(staff, { vertical: 'acme/crm' });
+                expect(recent.length).toBe(2);
+                expect(recent[0].operation).toBe('POST /verticals/:slug/previews');
+                // The lookup a CI log's `reference = <id>` line lands on.
+                const byRef = await host.admin.listOpsFailures(staff, { reference: 'testref123abc' });
+                expect(byRef.length).toBe(1);
+                expect(byRef[0].stage).toBe('wfp-upload');
+                expect(byRef[0].tenantId).toBe(t1);
+                expect(byRef[0].status).toBe(502);
+                // Cursor pages exactly like the audit log: the entry id IS the cursor.
+                const page1 = await host.admin.listOpsFailures(staff, { vertical: 'acme/crm', limit: 1 });
+                const page2 = await host.admin.listOpsFailures(staff, {
+                    vertical: 'acme/crm',
+                    limit: 1,
+                    cursor: page1[0].id,
+                });
+                expect(page1.length).toBe(1);
+                expect(page2.length).toBe(1);
+                expect(page2[0].id).not.toBe(page1[0].id);
+            });
+            it('bounds the recorded message — a runaway upstream body never becomes a runaway row', async () => {
+                await host.admin.recordOpsFailure({
+                    actor: staff,
+                    operation: 'contract.bound-check',
+                    message: 'x'.repeat(10_000),
+                });
+                const rows = await host.admin.listOpsFailures(staff, { operation: 'contract.bound-check' });
+                expect(rows.length).toBe(1);
+                expect(rows[0].message.length).toBeLessThanOrEqual(2000);
+            });
+        });
         //
         // The store exists so a vertical's connector can reach a tenant's provider
         // without any module ever holding a credential. So the properties that
@@ -1820,6 +2004,21 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.admin.promoteVersion(staff, 'egeryds/crm', 'prod', vid);
             expect((await host.admin.listChannels(staff, 'egeryds/crm')).find((c) => c.channel === 'prod')?.versionId).toBe(vid);
         });
+        it('getVersion reads ONE version by id, and fails closed across a lineage', async () => {
+            // The read that replaced "list every version this vertical ever pushed, then
+            // .find() one". Correctness first: same row, same shape as the list gives.
+            const vid = await publishPrivate('egeryds/crm', '0.9.0');
+            const one = await host.admin.getVersion(staff, vid);
+            expect(one?.id).toBe(vid);
+            expect(one).toEqual((await host.admin.listVersions(staff, 'egeryds/crm')).find((v) => v.id === vid));
+            // Narrowed, it keeps what the old `.find()`-inside-one-slug's-list gave for free:
+            // a version of ANOTHER vertical is absent, not returned across the boundary. Without
+            // this, the slug in the URL stops constraining which version a route can hand back.
+            expect((await host.admin.getVersion(staff, vid, 'egeryds/crm'))?.id).toBe(vid);
+            expect(await host.admin.getVersion(staff, vid, 'callout')).toBeUndefined();
+            // An id nobody published is absent, not a throw — callers branch on undefined.
+            expect(await host.admin.getVersion(staff, ulid())).toBeUndefined();
+        });
         it('a platform vertical still lands pending — auto-admission is scoped to private ownership', async () => {
             // 'callout' is platform-owned (ownerTenant null): the 9.9.9 push in the test
             // above landed pending. The distinction is the whole design: self-admission
@@ -1972,6 +2171,31 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 verticalSlug: 't-acme/crm',
             });
         });
+        it('listHostnames narrows to ONE vertical, in the query', async () => {
+            // The deploy path's surface-drift warning needs this vertical's bindings. It used
+            // to read the WHOLE fleet's rows and filter in JS, which made a push's advisory
+            // check depend on every other tenant's routing row being readable — one malformed
+            // row anywhere took down deploys for everyone. Narrowing belongs in the query, so
+            // the rows that answer the question are the only rows that can break it.
+            const other = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t1, scopeId: other, vertical: 'callout', jurisdiction: 'eu' });
+            await host.admin.bindHostname(staff, {
+                hostname: 'callout-narrow.global.example.com',
+                tenantId: t1,
+                scopeId: other,
+                surface: 'app',
+                region: null,
+                canonical: true,
+            });
+            const mine = await host.admin.listHostnames(staff, { verticalSlug: 't-acme/crm' });
+            expect(mine.length).toBeGreaterThan(0);
+            expect(mine.every((h) => h.verticalSlug === 't-acme/crm')).toBe(true);
+            expect(mine.map((h) => h.hostname)).not.toContain('callout-narrow.global.example.com');
+            // Composes with the other filters rather than replacing them, and an unknown slug
+            // is an empty list — never "no filter, here is everything".
+            expect(await host.admin.listHostnames(staff, { verticalSlug: 'no-such-vertical' })).toEqual([]);
+            expect(await host.admin.listHostnames(staff, { verticalSlug: 't-acme/crm', scopeId: other })).toEqual([]);
+        });
         it('routes two surfaces of ONE scope to different hostnames', async () => {
             // The reason §5.5's one-hostname-per-scope was not enough: the shop fronts a
             // storefront and a back office from the same data, and RallyPoint a player