@lovrozagar/oat 0.2.1 → 0.3.0

package/dist/runtime/checks.js

@@ -6,10 +6,29 @@
  * the oracle of what oat just wrote. Check ids are stable: the conformance suite asserts on them.
  */
 import { filterTerm, selectTerm, sortTerm } from "../spec/conventions.js";
+import { describeFeatureGate, isDocumentedFeatureGateDenial, reportFeatureGateSchemaDrift } from "./feature-gate.js";
 import { driveAsync } from "./async.js";
 import { buildCohort } from "./fixture.js";
 import { fillPath } from "./world.js";
 /* ------------------------------------------------------------------- helpers */
+/**
+ * A documented feature-gate 403 is not a 2xx-check failure and not SECURITY.
+ *
+ * The check that needed a success stands down with a named gap. The 403 body is still
+ * validated against the documented error schema — coverage is not a free pass for drift.
+ */
+function standDownForFeatureGate(ctx, op, exchange, check) {
+    if (op === undefined)
+        return false;
+    if (!isDocumentedFeatureGateDenial(op, exchange.status, exchange.responseBody))
+        return false;
+    if (ctx.validator !== undefined) {
+        reportFeatureGateSchemaDrift(ctx.findings, ctx.validator, op, ctx.model.rawOperations.get(op.operationId), exchange, ctx.entityName);
+    }
+    ctx.findings.gap(check, ctx.entityName, `${op.operationId} did not apply`, `${describeFeatureGate(op, exchange.responseBody)}. The check that needed a 2xx stands ` +
+        "down rather than treat the documented 403 as a defect.");
+    return true;
+}
 /** The list endpoint's derived conventions — parameter roles and envelope spellings. */
 function conv(ctx) {
     return ctx.listOp.conventions;
@@ -977,6 +996,8 @@ const patchMinimality = {
         const drifting = new Set([
             "updated_at",
             "modified_at",
+            /* A job's progress counter advances on GET without this PATCH having written it. */
+            "progress",
             /*
              * From both operations, not just the one being probed. A document commonly declares
              * its server-owned fields on `create` — that is where they are conspicuous, being the
@@ -1001,6 +1022,8 @@ const patchMinimality = {
             body: { [field]: "oat patched value" },
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, ctx.updateOp, patched, this.id))
+            return;
         if (patched.status >= 300)
             return;
         const after = await ctx.client.get(fillPath(ctx.readOp.path, params), { headers: ctx.auth() });
@@ -1077,6 +1100,8 @@ const immutableRejected = {
             body: { [field]: probe },
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, ctx.updateOp, patched, this.id))
+            return;
         if (patched.status >= 400)
             return;
         /* Read the echoed record first. Re-reading can itself fail once the write lands — writing
@@ -1177,6 +1202,8 @@ const deleteMissingIs404 = {
         const exchange = await ctx.client.request("DELETE", fillPath(ctx.deleteOp.path, params), {
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, ctx.deleteOp, exchange, this.id))
+            return;
         if (exchange.status === 404 || exchange.status === 410 || exchange.status === 400)
             return;
         if (exchange.status >= 300)
@@ -1202,6 +1229,8 @@ const softDeleteHidden = {
         const deleted = await ctx.client.request("DELETE", fillPath(ctx.deleteOp.path, params), {
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, ctx.deleteOp, deleted, this.id))
+            return;
         if (deleted.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `DELETE returned ${deleted.status}, so no tombstone was created to look for`);
         }
@@ -1290,10 +1319,14 @@ const idempotentReplay = {
         const path = fillPath(createOp.path, ctx.scope);
         const headers = { ...ctx.auth(), [header]: key };
         const first = await ctx.client.request("POST", path, { body, headers });
+        if (standDownForFeatureGate(ctx, createOp, first, this.id))
+            return;
         if (first.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `the first create returned ${first.status}, so there was nothing to replay`);
         }
         const second = await ctx.client.request("POST", path, { body, headers });
+        if (standDownForFeatureGate(ctx, createOp, second, this.id))
+            return;
         if (second.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `the replay returned ${second.status}; a repeated key must be answered, not refused`);
         }
@@ -1365,6 +1398,8 @@ const declaredInvalidationHappens = {
             body: validBody(ctx, schema),
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, createOp, created, this.id))
+            return;
         if (created.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `the create returned ${created.status}, so nothing was invalidated`);
         }
@@ -2508,25 +2543,20 @@ function pointerValue(body, pointer) {
  * at the same check — the timeline is the property.
  */
 const inviteGrantsThenRevokes = {
-    applicable: (ctx) => ctx.invite !== null &&
-        ctx.readOp !== undefined &&
-        ctx.records.length > 0 &&
-        ctx.actors.some((actor) => actor.inviteAs !== undefined &&
-            ctx.actors[0] !== undefined &&
-            !sameTenantScope(actor.roots, ctx.actors[0].roots)),
+    applicable: (ctx) => ctx.invite !== null && (ctx.readOp !== undefined || ctx.listOp !== undefined),
     dependsOn: ["list.read-after-write", "tenant.item-not-readable-cross-tenant"],
     id: "auth.invite-grants-then-revokes",
-    needs: "x-invite naming invite/accept/revoke, a peer principal with inviteAs, and an item route",
+    needs: "x-invite naming invite/accept/revoke, a peer principal with inviteAs, and an item or list route",
     async run(ctx) {
         const spec = ctx.invite;
         const owner = ctx.actors[0];
-        const target = ctx.records[0];
-        if (spec === null || owner === undefined || target === undefined || ctx.readOp === undefined) {
+        if (spec === null || owner === undefined) {
             return;
         }
-        const delegate = ctx.actors.find((actor) => actor.inviteAs !== undefined && !sameTenantScope(actor.roots, owner.roots));
+        const delegate = ctx.actors.find((actor) => actor !== owner && actor.inviteAs !== undefined && !sameTenantScope(actor.roots, owner.roots)) ?? ctx.actors.find((actor) => actor !== owner && actor.inviteAs !== undefined);
         if (delegate === undefined || delegate.inviteAs === undefined) {
-            return ctx.findings.unresolved(this.id, ctx.entityName, "no peer principal declares inviteAs, so there is no one to invite");
+            return ctx.findings.gap(this.id, ctx.entityName, "x-invite requires a peer principal with inviteAs", "x-invite names the grant flow, but no peer principal declares inviteAs, so oat " +
+                "cannot fill the grantee field without inventing an email");
         }
         const inviteOp = ctx.model.byOperationId.get(spec.invite);
         const acceptOp = ctx.model.byOperationId.get(spec.accept);
@@ -2534,26 +2564,35 @@ const inviteGrantsThenRevokes = {
         if (inviteOp === undefined || acceptOp === undefined || revokeOp === undefined) {
             return ctx.findings.unresolved(this.id, ctx.entityName, "x-invite names an operation that is not in the document");
         }
-        const id = String(target[ctx.identity]);
-        const resource = { ...ctx.scope, ...itemParamFor(ctx, id) };
-        const itemPath = ctx.readOp.path;
+        const target = ctx.records[0];
+        const id = target === undefined ? undefined : String(target[ctx.identity]);
+        const resource = {
+            ...ctx.scope,
+            ...(id === undefined ? {} : itemParamFor(ctx, id)),
+        };
+        const itemPath = ctx.readOp?.path;
         const canRead = async () => {
+            if (itemPath === undefined || id === undefined)
+                return null;
             const exchange = await ctx.client.get(fillPath(itemPath, { ...delegate.roots, ...resource }), {
                 headers: delegate.headers(),
             });
             return exchange.status < 300;
         };
-        if (await canRead()) {
+        const alreadyReadable = await canRead();
+        if (alreadyReadable === true) {
             return ctx.findings.unresolved(this.id, ctx.entityName, "the delegate could already read the record, so invite cannot be distinguished from a leak");
         }
         const invited = await ctx.client.request(inviteOp.method, fillPath(inviteOp.path, resource), {
             body: { [spec.granteeField]: delegate.inviteAs },
             headers: { ...owner.headers(), "content-type": "application/json" },
         });
+        if (standDownForFeatureGate(ctx, inviteOp, invited, this.id))
+            return;
         if (invited.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `invite returned ${invited.status}, so accept/revoke were never exercised`);
         }
-        if (await canRead()) {
+        if ((await canRead()) === true) {
             ctx.findings.backend(this.id, ctx.entityName, "an invite grants access before it is accepted", `inviting ${delegate.id} made ${ctx.entityName} ${id} readable immediately. The accept ` +
                 "step is then theatre — anyone who can be named in an invite body is already in.", [invited]);
             return;
@@ -2566,10 +2605,12 @@ const inviteGrantsThenRevokes = {
         const accepted = await ctx.client.request(acceptOp.method, fillPath(acceptOp.path, { token }), {
             headers: delegate.headers(),
         });
+        if (standDownForFeatureGate(ctx, acceptOp, accepted, this.id))
+            return;
         if (accepted.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `accept returned ${accepted.status}`);
         }
-        if (!(await canRead())) {
+        if ((await canRead()) === false) {
             ctx.findings.backend(this.id, ctx.entityName, "accepting an invite does not grant access", `${delegate.id} accepted an invite to ${ctx.entityName} ${id} and still cannot read it. ` +
                 "The invite flow completed; the grant did not.", [invited, accepted]);
             return;
@@ -2578,10 +2619,12 @@ const inviteGrantsThenRevokes = {
             return ctx.findings.unresolved(this.id, ctx.entityName, `invite response has no grant id at ${spec.grantPointer}, so revoke cannot be expressed`);
         }
         const revoked = await ctx.client.request(revokeOp.method, fillPath(revokeOp.path, { ...resource, grant_id: grantId }), { headers: owner.headers() });
+        if (standDownForFeatureGate(ctx, revokeOp, revoked, this.id))
+            return;
         if (revoked.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `revoke returned ${revoked.status}`);
         }
-        if (await canRead()) {
+        if ((await canRead()) === true) {
             ctx.findings.backend(this.id, ctx.entityName, "revoking an invite does not remove access", `${delegate.id} can still read ${ctx.entityName} ${id} after the grant was revoked. ` +
                 "A share that cannot be taken back is a standing leak.", [invited, accepted, revoked]);
         }
@@ -2771,6 +2814,8 @@ const enumValidated = {
             body,
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, createOp, exchange, this.id))
+            return;
         if (exchange.status >= 400)
             return;
         const declared = target.schema.enum.map((v) => JSON.stringify(v)).join(", ");
@@ -2800,6 +2845,8 @@ const maxLengthValidated = {
             body,
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, createOp, exchange, this.id))
+            return;
         if (exchange.status >= 400)
             return;
         ctx.findings.backend(this.id, ctx.entityName, "a string longer than the declared maxLength was accepted", `"${target.name}" declares maxLength ${max} but a ${max + 25}-character value was stored ` +
@@ -2827,6 +2874,8 @@ const requiredValidated = {
             body,
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, createOp, exchange, this.id))
+            return;
         if (exchange.status >= 400)
             return;
         ctx.findings.backend(this.id, ctx.entityName, "create succeeded without a required field", `"${field}" is listed in the schema's required array, but omitting it returned ` +
@@ -2851,6 +2900,8 @@ const contentTypeEnforced = {
             contentType: "text/plain",
             headers: ctx.auth(),
         });
+        if (standDownForFeatureGate(ctx, createOp, exchange, this.id))
+            return;
         if (exchange.status === 415 || exchange.status >= 400)
             return;
         ctx.findings.backend(this.id, ctx.entityName, "a non-JSON content type was accepted on a JSON endpoint", `the operation documents 415 and declares only a JSON request body, but a request sent ` +
@@ -2872,16 +2923,33 @@ const errorSchemaHonoured = {
             return;
         const params = { ...ctx.scope, ...itemParamFor(ctx, "oat-definitely-missing-id") };
         const exchange = await ctx.client.get(fillPath(readOp.path, params), { headers: ctx.auth() });
-        if (exchange.status < 400)
-            return;
-        if (!validator.documents(raw, exchange.status))
-            return;
-        const result = validator.validate(readOp.operationId, raw, exchange.status, exchange.responseBody);
-        if (result.ok)
-            return;
-        ctx.findings.spec(this.id, ctx.entityName, `${exchange.status} error body does not match its documented schema`, `${readOp.operationId} returned ${exchange.status} with a body that fails the schema the ` +
-            `document declares for it: ${result.errors.join("; ")}. Clients that parse errors ` +
-            "from the spec will not understand this response.", [exchange]);
+        if (exchange.status >= 400 && validator.documents(raw, exchange.status)) {
+            const result = validator.validate(readOp.operationId, raw, exchange.status, exchange.responseBody);
+            if (!result.ok) {
+                ctx.findings.spec(this.id, ctx.entityName, `${exchange.status} error body does not match its documented schema`, `${readOp.operationId} returned ${exchange.status} with a body that fails the schema the ` +
+                    `document declares for it: ${result.errors.join("; ")}. Clients that parse errors ` +
+                    "from the spec will not understand this response.", [exchange]);
+            }
+        }
+        /* A documented feature-gate 403 is coverage for the 2xx check, not for the error schema.
+         * Walk this entity's already-observed gate denials so an undeclared body is still drift. */
+        const seen = new Set();
+        for (const op of ctx.model.operations) {
+            if (op.entity !== ctx.entityName || op.featureGate === null)
+                continue;
+            const opRaw = ctx.model.rawOperations.get(op.operationId);
+            if (opRaw === undefined)
+                continue;
+            for (const prior of ctx.client.transcript) {
+                if (!isDocumentedFeatureGateDenial(op, prior.status, prior.responseBody))
+                    continue;
+                const key = `${op.operationId}:${prior.seq}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                reportFeatureGateSchemaDrift(ctx.findings, validator, op, opRaw, prior, ctx.entityName);
+            }
+        }
     },
 };
 const successSchemaHonoured = {
@@ -2917,9 +2985,24 @@ const successSchemaHonoured = {
 };
 /** Builds a body that should be accepted, for use as the base of a negative probe. */
 function validBody(ctx, schema) {
-    const [member] = buildCohort(schema, ctx.seed, ["baseline"]);
+    const [member] = buildCohort(schema, ctx.seed, ["baseline"], ctx.createOp?.operationId ?? ctx.entityName);
     return member?.body ?? {};
 }
+/** Invite bodies must carry the peer's `inviteAs`, never a generated email. */
+function bodyForOp(ctx, op) {
+    const body = validBody(ctx, requestSchemaOf(ctx, op) ?? {});
+    const spec = op.invite ?? ctx.invite;
+    if (spec === null || spec === undefined)
+        return body;
+    const owner = ctx.actors[0];
+    const delegate = ctx.actors.find((actor) => actor !== owner &&
+        actor.inviteAs !== undefined &&
+        owner !== undefined &&
+        !sameTenantScope(actor.roots, owner.roots)) ?? ctx.actors.find((actor) => actor !== owner && actor.inviteAs !== undefined);
+    if (delegate?.inviteAs !== undefined)
+        body[spec.granteeField] = delegate.inviteAs;
+    return body;
+}
 function requestSchemaOf(ctx, op) {
     const raw = ctx.model.rawOperations.get(op.operationId);
     const content = raw?.requestBody?.content;
@@ -3085,6 +3168,10 @@ const noLostUpdate = {
                 headers: ctx.auth(),
             }),
         ]);
+        if (standDownForFeatureGate(ctx, ctx.updateOp, firstWrite, this.id))
+            return;
+        if (standDownForFeatureGate(ctx, ctx.updateOp, secondWrite, this.id))
+            return;
         if (firstWrite.status >= 300 || secondWrite.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `a concurrent PATCH was rejected (${firstWrite.status}, ${secondWrite.status}), so no ` +
                 "race actually took place");
@@ -3175,11 +3262,13 @@ const declaredEffectsOccur = {
                 const before = await observe(ctx, listOp);
                 if (before === null)
                     continue;
-                const body = op.hasRequestBody ? validBody(ctx, requestSchemaOf(ctx, op) ?? {}) : undefined;
+                const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
                 const invoked = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
                     headers: ctx.auth(),
                     ...(body === undefined ? {} : { body }),
                 });
+                if (standDownForFeatureGate(ctx, op, invoked, this.id))
+                    continue;
                 if (invoked.status >= 400) {
                     ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} could not be invoked`, `returned ${invoked.status}; its declared effects are unverified`);
                     continue;
@@ -3245,11 +3334,13 @@ const asyncReachesTerminalState = {
             const spec = op.async;
             if (spec === null)
                 continue;
-            const body = op.hasRequestBody ? validBody(ctx, requestSchemaOf(ctx, op) ?? {}) : undefined;
+            const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
             const start = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
                 headers: ctx.auth(),
                 ...(body === undefined ? {} : { body }),
             });
+            if (standDownForFeatureGate(ctx, op, start, this.id))
+                continue;
             if (start.status >= 400) {
                 ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} could not be started`, `returned ${start.status}; the async lifecycle after it is untested`);
                 continue;