fix(api): refuse a wildcard mixed with a tag, and bound every echoed segment

All four findings verified against the code; all four were real.

`If-Match: *, "7"` was answered `AnyExisting`. RFC 9110 § 13.1.1 makes the
wildcard an alternative to the tag list — `If-Match = "*" / #entity-tag` — not a
member of it, so a mixed list is a malformed precondition. Measured:
Microsoft's `TryParseStrictList` accepts it as a two-element list, and the loop
returned on the first `*` it saw, in either order. The result was the *weaker*
reading of a header the API could not understand — "any version, as long as it
exists" answered to a client that had also named one — which is the exact
failure this type refuses one paragraph above, wearing a different shape. Four
cases cover both orderings through both entry points; all four go red against
the old branch.

`SortSpecification` bounded the value it quotes back on the term-count path and
not on the per-segment one, so a `sort` with no commas — which never reaches
that guard — arrived whole. An 8 KB single field was echoed into a Problem
Details body and every log line carrying one. Both paths go through one
`Bounded` helper now.

Two more holes in my own scanner, both in the same method the last round
touched. `CopyLiteral` treated a raw string literal's first quote as its
terminator, so `"""…"""` put the scanner back into code while it was still
inside a string — and a `//` there swallowed the rest of the line again, which
is the bug the literal tracking was added to fix. It records the opening quote
run and closes only on a run of the same length. A probe carrying a raw literal
with a quote, a `//` and a banned literal now fails the rule, and so does a
`Request.Host` on the line after it — which is what proves the scanner exits the
literal rather than staying in it.

And the frontend architecture document showed the middleware setting
`x-learnstack-host` under a comment claiming it was "what the SDK states to the
API", conflating the inward carry with the outward statement and never showing
the hop secret at all. They are now two things: the middleware carries the host
inward, and the SDK pairs it with the secret from server configuration on the
way out — with the reason the secret is not in the middleware said outright,
which is that a secret written into a forwarded request header travels further
than the one hop it authenticates.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cemililik

backend/src/LearnStack.Api/Common/EntityTag.cs

@@ -113,14 +113,23 @@ public static Assertion ReadAssertion(HttpRequest request, out IReadOnlyList<lon
             return Assertion.Malformed;
         }
 
+        // RFC 9110 § 13.1.1: `If-Match = "*" / #entity-tag`. The wildcard is one
+        // of two alternatives, not a member of the list — so `*, "7"` is not a
+        // wildcard with extra detail, it is a malformed precondition.
+        // `TryParseStrictList` accepts it as a two-element list (measured), and
+        // reading the `*` out of it would answer "any version, as long as it
+        // exists" to a client that also named one. That is the same failure this
+        // type refuses one paragraph up, wearing a different shape: the weaker
+        // interpretation of something it could not understand.
+        if (tags.Any(tag => tag.Equals(EntityTagHeaderValue.Any)))
+        {
+            return tags.Count == 1 ? Assertion.AnyExisting : Assertion.Malformed;
+        }
+
         var asserted = new List<long>(tags.Count);
 
         foreach (var tag in tags)
         {
-            if (tag.Equals(EntityTagHeaderValue.Any))
-            {
-                return Assertion.AnyExisting;
-            }
 
             // Strong comparison: a weak tag says "semantically equivalent", and
             // two versions of a row that are semantically equivalent are still

backend/src/LearnStack.SharedKernel/Pagination/SortSpecification.cs

@@ -127,9 +127,7 @@ public static bool TryParse(
             // whole client-supplied value — an 8 KB `sort` is exactly the input
             // this guard exists to reject, and echoing it whole puts it in a
             // Problem Details body and every log line that carries one.
-            offendingSegment = raw.Length > MaxFieldLength
-                ? raw[..MaxFieldLength]
-                : raw;
+            offendingSegment = Bounded(raw);
             return false;
         }
 
@@ -149,7 +147,11 @@ public static bool TryParse(
             // a key the client believes it asked for.
             if (!IsWellFormedField(field) || !seen.Add(field))
             {
-                offendingSegment = segment;
+                // Bounded for the same reason the term-count guard above is: a
+                // `sort` with no commas never reaches that guard, so an 8 KB
+                // single field arrives here whole and would be quoted back into
+                // a Problem Details body and every log line carrying one.
+                offendingSegment = Bounded(segment);
                 return false;
             }
 
@@ -224,6 +226,13 @@ public Result<SortSpecification> Restrict(IReadOnlyCollection<string> allowedFie
     /// rather than left for the endpoint's allow-list, so a value that could
     /// only have come from a malformed client never travels further in.
     /// </summary>
+    /// <summary>
+    /// The most of a rejected value this type will quote back. Nothing the
+    /// client sent leaves here longer than a single field is allowed to be.
+    /// </summary>
+    private static string Bounded(string value) =>
+        value.Length > MaxFieldLength ? value[..MaxFieldLength] : value;
+
     private static bool IsWellFormedField(string field)
     {
         if (field.Length == 0 || field.Length > MaxFieldLength)

backend/tests/LearnStack.Tests.Architecture/TenancyConventionTests.cs

@@ -194,12 +194,33 @@ private static string WithoutComments(string source)
     }
 
     /// <summary>Copies one string or character literal and returns the index after it.</summary>
+    /// <remarks>
+    /// Three shapes, because C# has three and they terminate differently: a
+    /// normal literal ends at an unescaped quote, a verbatim one (<c>@"…"</c>)
+    /// escapes a quote by doubling it, and a raw one opens with a <b>run</b> of
+    /// three or more quotes and closes only on a run of the same length. Reading
+    /// a raw literal's first quote as its terminator puts the scanner back
+    /// inside code while it is still inside a string — which is how a <c>//</c>
+    /// there would swallow the rest of the line again.
+    /// </remarks>
     private static int CopyLiteral(string source, int start, System.Text.StringBuilder kept)
     {
         var quote = source[start];
 
-        // Raw string literals ("""…""") have no escapes and end on a matching
-        // run of quotes; verbatim ones (@"…") escape a quote by doubling it.
+        if (quote == '"')
+        {
+            var opening = 0;
+            while (start + opening < source.Length && source[start + opening] == '"')
+            {
+                opening++;
+            }
+
+            if (opening >= 3)
+            {
+                return CopyRawLiteral(source, start, opening, kept);
+            }
+        }
+
         var verbatim = start > 0 && source[start - 1] == '@';
         var i = start;
 
@@ -230,8 +251,8 @@ private static int CopyLiteral(string source, int start, System.Text.StringBuild
                 return i + 1;
             }
 
-            // An unterminated literal cannot span a line unless it is verbatim;
-            // bailing keeps a malformed file from swallowing the whole scan.
+            // An unterminated non-verbatim literal cannot span a line; bailing
+            // keeps a malformed file from swallowing the rest of the scan.
             if (!verbatim && c == '\n')
             {
                 return i;
@@ -244,6 +265,41 @@ private static int CopyLiteral(string source, int start, System.Text.StringBuild
         return i;
     }
 
+    /// <summary>Copies a raw string literal, closing only on a run of the opening length.</summary>
+    private static int CopyRawLiteral(
+        string source, int start, int opening, System.Text.StringBuilder kept)
+    {
+        var i = start;
+        kept.Append(source, i, opening);
+        i += opening;
+
+        while (i < source.Length)
+        {
+            if (source[i] != '"')
+            {
+                kept.Append(source[i]);
+                i++;
+                continue;
+            }
+
+            var run = 0;
+            while (i + run < source.Length && source[i + run] == '"')
+            {
+                run++;
+            }
+
+            kept.Append(source, i, run);
+            i += run;
+
+            if (run >= opening)
+            {
+                return i;
+            }
+        }
+
+        return i;
+    }
+
     private static string WithoutWhitespace(string value) =>
         string.Concat(value.Where(character => !char.IsWhiteSpace(character)));
 }

backend/tests/LearnStack.Tests.Unit/Api/Common/EntityTagTests.cs

@@ -127,6 +127,29 @@ public void Every_Asserted_Version_In_A_List_Is_Read()
         versions.Should().Equal(5, 6, 7);
     }
 
+    [Theory]
+    [InlineData("*, \"7\"")]
+    [InlineData("\"7\", *")]
+    public void A_Wildcard_Mixed_With_A_Tag_Is_Malformed_Not_A_Wildcard(string raw)
+    {
+        // RFC 9110 § 13.1.1 makes `*` an alternative to the tag list, not a
+        // member of it. Microsoft's parser accepts the mixed form as a
+        // two-element list, so reading the `*` out of it would answer "any
+        // version, as long as it exists" to a client that also named one —
+        // the weaker interpretation of a header the API could not understand,
+        // which is the failure Evaluate refuses everywhere else.
+        ReadAssertion(raw, out var versions).Should().Be(EntityTag.Assertion.Malformed);
+        versions.Should().BeEmpty();
+    }
+
+    [Theory]
+    [InlineData("*, \"7\"")]
+    [InlineData("\"7\", *")]
+    public void And_Evaluate_Fails_It_Rather_Than_Matching(string raw)
+    {
+        Evaluate(raw, 7).Should().Be(EntityTag.Precondition.Failed);
+    }
+
     [Theory]
     [InlineData(null, EntityTag.Assertion.Absent)]
     [InlineData("*", EntityTag.Assertion.AnyExisting)]

docs/architecture/14-frontend-architecture.md

@@ -105,9 +105,11 @@ export async function middleware(req: NextRequest) {
   if (resolved.organizationId) requestHeaders.set('x-organization-id', resolved.organizationId);
   requestHeaders.set('x-locale', locale);
 
-  // What the server-side SDK actually states to the API on the way out, over
-  // the authenticated hop. The host — not the tenant — is the input the API
-  // resolves from.
+  // The visitor's host, carried INWARD so the server-side SDK can state it to
+  // the API. The host — not the tenant — is the input the API resolves from.
+  // The hop SECRET is deliberately not here: it is server configuration, and a
+  // secret written into a forwarded request header travels further than the one
+  // hop it authenticates.
   requestHeaders.set('x-learnstack-host', host);
 
   return NextResponse.next({ request: { headers: requestHeaders } });
@@ -118,6 +120,28 @@ export const config = {
 };
 ```
 
+The SDK is what states the hop, on the way **out**. It reads the host the
+middleware carried inward and pairs it with the secret from server configuration
+— which is why `createServerSdk` is a server-only entry point and why the secret
+never appears in the middleware above:
+
+```ts
+// packages/sdk/src/server.ts — the shape, once the first operation exists.
+const response = await fetch(new URL(path, options.apiBaseUrl), {
+  headers: {
+    // The trusted hop: both halves, or the API ignores the host header
+    // entirely and resolves from its own Host (ADR-0036).
+    'X-LearnStack-Host': options.host,
+    'X-LearnStack-Hop-Secret': process.env.LEARNSTACK_HOP_SECRET!,
+
+    // An assertion, not a selector. The API compares it against the host it
+    // resolved for itself; a mismatch is a 404.
+    'X-Tenant-Id': options.tenantId,
+    'Accept-Language': options.locale,
+  },
+});
+```
+
 `resolveHost` is backed by a short-TTL edge cache (~60 s) that calls the LearnStack API,
 which in turn reads the `platform_host_to_tenant` projection (populated by the Hub —
 [27-custom-domain-tls.md](27-custom-domain-tls.md)). Custom-domain activations and