@reventlessdev/reventless-core 3.0.0-alpha.233 → 3.0.0-alpha.234

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.234 (2026-08-14)
+
+### Features
+
+* **core:** one contract for which refusal a platform gave ([7705c13](https://github.com/ReventlessDev/reventless-core/commit/7705c13ec63f41a3a659bc98cfb45b880fd5b222))
+
+
 # 3.0.0-alpha.233 (2026-08-14)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.233",
+  "version": "3.0.0-alpha.234",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,16 +29,16 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.6",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
     "@reventlessdev/rescript-node": "2.0.0-alpha.6",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.6",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.140",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.113",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.31"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.141",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.31",
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.113"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/adapter/Auth/Auth_RefusalVocabulary.res

@@ -0,0 +1,168 @@
+// The cross-provider contract for "which refusal did I just get" — see
+// [docs/plans/appsync-refusal-vocabulary.md].
+//
+// An authorization gate has two ways to refuse and they ask the caller for
+// opposite things. A caller whose credentials did not verify should present new
+// ones. A caller who is simply not entitled will meet the same answer however
+// many times they authenticate — asking them to sign in again ends a working
+// session and fixes nothing.
+//
+// Both adapters draw that distinction. They express it in shapes that have
+// nothing in common, because neither chose its own vocabulary: the local adapter
+// sets `extensions.code` on a GraphQL error, and AppSync refuses at two
+// different layers with `errorType` values the service picks. A client written
+// against one is quietly wrong against the other — it reads for a key that is
+// never present, finds nothing, and proceeds as though nothing was refused.
+//
+// So this module is a mapping, not an equality. It cannot make the two paths
+// answer alike; `extensions` is not even reachable from an AppSync resolver.
+// What it can do is let a caller ask the one question that matters — *was this
+// about entitlement or about identity?* — and get an answer without knowing
+// which adapter it is talking to.
+//
+// Every row here is an observed response, captured against a deployed API and
+// the local server, not a reading of documentation.
+
+/**
+Which of the two refusals a response carries.
+
+`Entitlement` — the caller was identified and is not permitted. Re-authenticating
+changes nothing; the session is still good.
+
+`Identity` — the caller was not identified. New credentials are the remedy, and
+discarding the session is correct here and only here.
+*/
+type refusalKind =
+  | Entitlement
+  | Identity
+
+/** The adapter a signal belongs to. */
+type adapter =
+  | Local
+  | AppSync
+
+/**
+One observed refusal shape.
+
+`discriminator` names where a client looks; `value` is what it finds there.
+Together with `httpStatus` they are sufficient to classify a response — see
+[classify], which is what callers should use rather than re-deriving this.
+*/
+type signal = {
+  adapter: adapter,
+  kind: refusalKind,
+  httpStatus: int,
+  discriminator: string,
+  value: string,
+}
+
+/**
+The `extensions.code` the local adapter sets for each refusal.
+
+Exported so the adapter emits these rather than repeating the literals: a table
+the emitting code does not read is documentation, and documentation drifts. The
+AppSync values have no equivalent here — the service picks those, which is the
+whole reason this module is a mapping rather than a shared constant.
+*/
+let localEntitlementCode = "FORBIDDEN"
+
+/** See [localEntitlementCode]. */
+let localIdentityCode = "UNAUTHORIZED"
+
+/**
+The correspondence both adapters are held to.
+
+🚨 **The two AppSync values differ by a suffix and mean opposite things.**
+`Unauthorized` is the entitlement refusal; `UnauthorizedException` is the identity
+one. A client matching on the substring `"Unauthorized"` — the obvious thing to
+write — collapses exactly the distinction this table exists to preserve, and
+collapses it in the dangerous direction: it treats "you lack the role" as "your
+session is dead" and signs the caller out of a session that was working.
+
+Use [classify]. It is the only reason this table is data rather than prose.
+*/
+let signals: array<signal> = [
+  {
+    adapter: Local,
+    kind: Entitlement,
+    httpStatus: 200,
+    discriminator: "extensions.code",
+    value: localEntitlementCode,
+  },
+  {
+    adapter: Local,
+    kind: Identity,
+    httpStatus: 200,
+    discriminator: "extensions.code",
+    value: localIdentityCode,
+  },
+  {
+    adapter: AppSync,
+    kind: Entitlement,
+    httpStatus: 200,
+    discriminator: "errors[].errorType",
+    value: "Unauthorized",
+  },
+  {
+    // The request never becomes a GraphQL execution: the service rejects it
+    // before the schema is reached, so there is no field error to read and the
+    // status line is the whole answer.
+    adapter: AppSync,
+    kind: Identity,
+    httpStatus: 401,
+    discriminator: "x-amzn-errortype",
+    value: "UnauthorizedException",
+  },
+]
+
+/**
+Classify a refusal without knowing which adapter produced it.
+
+Pass what the response actually carried: its status, the `errorType` of a GraphQL
+error if there was one, and `extensions.code` if there was one. Returns `None`
+when the response is not a refusal this contract recognises — which includes a
+successful response, so a caller must not read `None` as "allowed".
+
+Ordering matters and is the point of the function. The transport status is
+checked first, because a 401 is the identity refusal on the AppSync path and its
+`x-amzn-errortype` (`UnauthorizedException`) shares a prefix with the entitlement
+value (`Unauthorized`). Matching the error type first would classify every
+unidentified AppSync caller as merely unentitled.
+*/
+let classify = (
+  ~httpStatus: int,
+  ~errorType: option<string>=?,
+  ~extensionsCode: option<string>=?,
+): option<refusalKind> =>
+  if httpStatus == 401 {
+    Some(Identity)
+  } else {
+    switch extensionsCode {
+    | Some(c) if c == localEntitlementCode => Some(Entitlement)
+    | Some(c) if c == localIdentityCode => Some(Identity)
+    | _ =>
+      switch errorType {
+      // Exact match, never a prefix or `includes` — see the warning on [signals].
+      | Some("Unauthorized") => Some(Entitlement)
+      | Some("UnauthorizedException") => Some(Identity)
+      | _ => None
+      }
+    }
+  }
+
+/** The signals one adapter can produce. */
+let signalsFor = (adapter: adapter): array<signal> =>
+  signals->Array.filter(s => s.adapter == adapter)
+
+/**
+Whether a refusal means the caller should be asked to authenticate again.
+
+The one decision the distinction exists to drive, kept here so no client has to
+re-derive it — and so the wrong answer cannot be arrived at independently in
+several places.
+*/
+let warrantsReauthentication = (kind: refusalKind): bool =>
+  switch kind {
+  | Identity => true
+  | Entitlement => false
+  }

package/src/adapter/Auth/Auth_RefusalVocabulary.res.mjs

@@ -0,0 +1,80 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let localEntitlementCode = "FORBIDDEN";
+
+let localIdentityCode = "UNAUTHORIZED";
+
+let signals = [
+  {
+    adapter: "Local",
+    kind: "Entitlement",
+    httpStatus: 200,
+    discriminator: "extensions.code",
+    value: localEntitlementCode
+  },
+  {
+    adapter: "Local",
+    kind: "Identity",
+    httpStatus: 200,
+    discriminator: "extensions.code",
+    value: localIdentityCode
+  },
+  {
+    adapter: "AppSync",
+    kind: "Entitlement",
+    httpStatus: 200,
+    discriminator: "errors[].errorType",
+    value: "Unauthorized"
+  },
+  {
+    adapter: "AppSync",
+    kind: "Identity",
+    httpStatus: 401,
+    discriminator: "x-amzn-errortype",
+    value: "UnauthorizedException"
+  }
+];
+
+function classify(httpStatus, errorType, extensionsCode) {
+  if (httpStatus === 401) {
+    return "Identity";
+  }
+  if (extensionsCode !== undefined) {
+    if (extensionsCode === localEntitlementCode) {
+      return "Entitlement";
+    }
+    if (extensionsCode === localIdentityCode) {
+      return "Identity";
+    }
+  }
+  if (errorType === undefined) {
+    return;
+  }
+  switch (errorType) {
+    case "Unauthorized" :
+      return "Entitlement";
+    case "UnauthorizedException" :
+      return "Identity";
+    default:
+      return;
+  }
+}
+
+function signalsFor(adapter) {
+  return signals.filter(s => s.adapter === adapter);
+}
+
+function warrantsReauthentication(kind) {
+  return kind !== "Entitlement";
+}
+
+export {
+  localEntitlementCode,
+  localIdentityCode,
+  signals,
+  classify,
+  signalsFor,
+  warrantsReauthentication,
+}
+/* No side effect */

package/src/components/Dcb/Dcb_Builder.res

@@ -895,7 +895,7 @@ module Make = (
         //
         // Stage E2: a DCB StateChangeSlice has a single GraphQL field but its
         // command type may declare multiple constructors with different
-        // authorization rules. The @aws_auth directive operates at field
+        // authorization rules. The Cognito group directive operates at field
         // granularity, so we read the auth for the first constructor (matching
         // the existing dcbTags convention at line 549 above). When all
         // constructors share the file-level default, this is exact; when they

package/src/plugin/lifecycle/PluginSpec.res

@@ -17,7 +17,7 @@ type command =
   | @noApi Connect(pluginDefinition)
   | @noApi Disconnect(version)
   // Admin lifecycle commands — API-exposed (auto-derived admin mutations,
-  // Cognito @aws_auth gated). `version` selects which known version to act on.
+  // Cognito group-gated). `version` selects which known version to act on.
   | Activate(version)
   | Deactivate(version)
   // Records a protocol-version incompatibility without changing connection state.

package/tests/adapter/RefusalVocabularyTest.res

@@ -0,0 +1,93 @@
+open JestGlobals
+
+// The contract in Auth_RefusalVocabulary is a mapping between two adapters that
+// cannot answer alike. The AWS rows cannot be asserted from a checkout — they
+// need a deployed API — so what is asserted here is the *table*: that it names
+// both adapters, that entitlement stays distinguishable from identity in each,
+// and that `classify` resolves the collision the two AppSync values create.
+//
+// Observed bodies behind these rows: docs/plans/appsync-group-authorization-unenforced.md §8.
+
+open ReventlessCore.Auth_RefusalVocabulary
+
+describe("Auth_RefusalVocabulary — the table", () => {
+  testSync("names both adapters", () => {
+    expect(signalsFor(Local)->Array.length)->toBeGreaterThan(0)
+    expect(signalsFor(AppSync)->Array.length)->toBeGreaterThan(0)
+  })
+
+  testSync("each adapter can express both refusals", () => {
+    [Local, AppSync]->Array.forEach(adapter => {
+      let kinds = signalsFor(adapter)->Array.map(s => s.kind)
+      expect(kinds->Array.includes(Entitlement))->toBe(true)
+      expect(kinds->Array.includes(Identity))->toBe(true)
+    })
+  })
+
+  testSync("within an adapter the two refusals are actually distinguishable", () => {
+    // A mapping whose two rows look identical to a client would be worthless —
+    // it has to differ in the status, the place to look, or the value found.
+    [Local, AppSync]->Array.forEach(adapter => {
+      let signals = signalsFor(adapter)
+      let entitlement = signals->Array.find(s => s.kind == Entitlement)
+      let identity = signals->Array.find(s => s.kind == Identity)
+      switch (entitlement, identity) {
+      | (Some(e), Some(i)) =>
+        let differs =
+          e.httpStatus != i.httpStatus || e.discriminator != i.discriminator || e.value != i.value
+        expect(differs)->toBe(true)
+      | _ => JsError.throwWithMessage("adapter is missing one of the two refusals")
+      }
+    })
+  })
+})
+
+describe("Auth_RefusalVocabulary.classify", () => {
+  testSync("classifies every row of the table as that row's kind", () => {
+    signals->Array.forEach(s => {
+      let errorType = s.discriminator->String.includes("errorType") ? Some(s.value) : None
+      let extensionsCode = s.discriminator == "extensions.code" ? Some(s.value) : None
+      // The 401 row's discriminator is a response header; status alone carries it.
+      expect(classify(~httpStatus=s.httpStatus, ~errorType?, ~extensionsCode?))->toEqual(Some(s.kind))
+    })
+  })
+
+  // The trap the table exists to defuse: on AppSync the entitlement value is a
+  // strict prefix of the identity one. A client matching by substring collapses
+  // them, and collapses them the dangerous way — signing out a caller whose
+  // session was fine.
+  testSync("Unauthorized and UnauthorizedException are opposite answers", () => {
+    expect(classify(~httpStatus=200, ~errorType="Unauthorized"))->toEqual(Some(Entitlement))
+    expect(classify(~httpStatus=401, ~errorType="UnauthorizedException"))->toEqual(Some(Identity))
+  })
+
+  testSync("a 401 is identity even when a field error would say otherwise", () => {
+    // Status is checked first precisely so this cannot go the other way.
+    expect(classify(~httpStatus=401, ~errorType="Unauthorized"))->toEqual(Some(Identity))
+  })
+
+  testSync("the local codes map to the same two kinds as the AppSync shapes", () => {
+    expect(classify(~httpStatus=200, ~extensionsCode="FORBIDDEN"))->toEqual(Some(Entitlement))
+    expect(classify(~httpStatus=200, ~extensionsCode="UNAUTHORIZED"))->toEqual(Some(Identity))
+  })
+
+  testSync("an unrecognised response is None, which is not 'allowed'", () => {
+    expect(classify(~httpStatus=200))->toEqual(None)
+    expect(classify(~httpStatus=200, ~errorType="ValidationError"))->toEqual(None)
+    expect(classify(~httpStatus=500))->toEqual(None)
+  })
+})
+
+describe("Auth_RefusalVocabulary.warrantsReauthentication", () => {
+  testSync("only an identity refusal asks the caller for new credentials", () => {
+    expect(warrantsReauthentication(Identity))->toBe(true)
+    expect(warrantsReauthentication(Entitlement))->toBe(false)
+  })
+
+  testSync("no adapter's entitlement refusal ends a session", () => {
+    // The regression this whole contract exists to prevent, stated once.
+    signals
+    ->Array.filter(s => s.kind == Entitlement)
+    ->Array.forEach(s => expect(warrantsReauthentication(s.kind))->toBe(false))
+  })
+})

package/tests/adapter/RefusalVocabularyTest.res.mjs

@@ -0,0 +1,79 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Auth_RefusalVocabulary$ReventlessCore from "../../src/adapter/Auth/Auth_RefusalVocabulary.res.mjs";
+
+globalThis.describe("Auth_RefusalVocabulary — the table", () => {
+  globalThis.test("names both adapters", () => {
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.signalsFor("Local").length).toBeGreaterThan(0);
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.signalsFor("AppSync").length).toBeGreaterThan(0);
+  });
+  globalThis.test("each adapter can express both refusals", () => {
+    [
+      "Local",
+      "AppSync"
+    ].forEach(adapter => {
+      let kinds = Auth_RefusalVocabulary$ReventlessCore.signalsFor(adapter).map(s => s.kind);
+      globalThis.expect(kinds.includes("Entitlement")).toBe(true);
+      globalThis.expect(kinds.includes("Identity")).toBe(true);
+    });
+  });
+  globalThis.test("within an adapter the two refusals are actually distinguishable", () => {
+    [
+      "Local",
+      "AppSync"
+    ].forEach(adapter => {
+      let signals = Auth_RefusalVocabulary$ReventlessCore.signalsFor(adapter);
+      let entitlement = signals.find(s => s.kind === "Entitlement");
+      let identity = signals.find(s => s.kind === "Identity");
+      if (entitlement === undefined) {
+        return Stdlib_JsError.throwWithMessage("adapter is missing one of the two refusals");
+      }
+      if (identity === undefined) {
+        return Stdlib_JsError.throwWithMessage("adapter is missing one of the two refusals");
+      }
+      let differs = entitlement.httpStatus !== identity.httpStatus || entitlement.discriminator !== identity.discriminator || entitlement.value !== identity.value;
+      globalThis.expect(differs).toBe(true);
+    });
+  });
+});
+
+globalThis.describe("Auth_RefusalVocabulary.classify", () => {
+  globalThis.test("classifies every row of the table as that row's kind", () => {
+    Auth_RefusalVocabulary$ReventlessCore.signals.forEach(s => {
+      let errorType = s.discriminator.includes("errorType") ? s.value : undefined;
+      let extensionsCode = s.discriminator === "extensions.code" ? s.value : undefined;
+      globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(s.httpStatus, errorType, extensionsCode)).toEqual(s.kind);
+    });
+  });
+  globalThis.test("Unauthorized and UnauthorizedException are opposite answers", () => {
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(200, "Unauthorized", undefined)).toEqual("Entitlement");
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(401, "UnauthorizedException", undefined)).toEqual("Identity");
+  });
+  globalThis.test("a 401 is identity even when a field error would say otherwise", () => {
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(401, "Unauthorized", undefined)).toEqual("Identity");
+  });
+  globalThis.test("the local codes map to the same two kinds as the AppSync shapes", () => {
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(200, undefined, "FORBIDDEN")).toEqual("Entitlement");
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(200, undefined, "UNAUTHORIZED")).toEqual("Identity");
+  });
+  globalThis.test("an unrecognised response is None, which is not 'allowed'", () => {
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(200, undefined, undefined)).toEqual(undefined);
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(200, "ValidationError", undefined)).toEqual(undefined);
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.classify(500, undefined, undefined)).toEqual(undefined);
+  });
+});
+
+globalThis.describe("Auth_RefusalVocabulary.warrantsReauthentication", () => {
+  globalThis.test("only an identity refusal asks the caller for new credentials", () => {
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.warrantsReauthentication("Identity")).toBe(true);
+    globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.warrantsReauthentication("Entitlement")).toBe(false);
+  });
+  globalThis.test("no adapter's entitlement refusal ends a session", () => {
+    Auth_RefusalVocabulary$ReventlessCore.signals.filter(s => s.kind === "Entitlement").forEach(s => {
+      globalThis.expect(Auth_RefusalVocabulary$ReventlessCore.warrantsReauthentication(s.kind)).toBe(false);
+    });
+  });
+});
+
+/*  Not a pure module */