OR semantics in perm query arg, strict parsing, segment-aware wildcards

perm=a|b+c now means (a or b) and c; repeated perm args remain ANDed.
Out-of-spec values (empty alternatives, chars outside the scope charset,
stray %2B) are rejected with 400 instead of being silently misparsed;
extra spaces between groups are tolerated. Forward endpoint 400/500
details name /auth/api/forward as origin without echoing query args.
Wildcards are now filename-like: * stays within a :- or /-separated
segment, ** spans segments, partial segments allowed. Slash added to
allowed scope characters for path-based permissions.

docs/api/forward.md

@@ -34,10 +34,11 @@ Connection hop-by-hop headers (Connection, Upgrade, Transfer-Encoding, etc.) mus
 
 No response body. Only [Remote headers](../Headers.md) are set on the response and your proxy should forward them to the backend request. The headers, not a response body, are the whole point of this endpoint: they are how the authenticated identity reaches the protected service, which can trust them because it is only reachable through the proxy.
 
-### Failure (401 / 403)
+### Failure (400 / 401 / 403)
 
 | Status | Meaning |
 |---|---|
+| 400 | Malformed perm argument (see [perm](perm.md#syntax-errors)). The error detail names `/auth/api/forward` as the origin and never echoes query arguments. |
 | 401 | Session missing or expired, or max_age not satisfied — the user needs to (re)authenticate. |
 | 403 | Requested permissions are missing — the forbidden flow allows signing in with another account. |
 

docs/api/perm.md

@@ -15,7 +15,7 @@ Repeat the query parameter for each required scope:
 ?perm=myapp:read&perm=myapp:write
 ```
 
-You can also pass multiple scopes in one parameter by separating them with whitespace:
+You can also pass multiple scopes in one parameter by separating them with whitespace (a literal space, i.e. `+` or `%20` in the query string):
 
 ```text
 ?perm=myapp:read%20myapp:write
@@ -25,19 +25,39 @@ Both forms produce the same result.
 
 ## Semantics
 
-The perm argument uses **AND** semantics: **every** listed scope must be present in the effective permissions for the request to succeed. If any required scope is missing, the endpoint returns 403.
+The perm argument uses **AND** semantics between groups: **every** listed scope group must be satisfied by the effective permissions for the request to succeed. If any required group is not satisfied, the endpoint returns 403.
 
-There is **no OR** support inside a single call. If you need to check "scope A or scope B", make separate calls or check the returned permission list in your own backend.
+Within a single group, use `|` to list alternatives with **OR** semantics — the group is satisfied when **any one** of the alternatives is present:
+
+```text
+?perm=myapp:read|myapp:write+myapp:login
+```
+
+This requires `myapp:login` **and** (`myapp:read` **or** `myapp:write`). No whitespace is allowed around the `|` operator.
+
+## Syntax errors
+
+Parsing is strict: anything out of spec is rejected with **400 Bad Request** rather than guessed at. This includes:
+
+- Empty values or alternatives (`?perm=`, `?perm=a||b`, `?perm=|a`, `?perm=a|`)
+- Whitespace around `|` (`?perm=a+|+b`)
+- Characters not allowed in scopes other than the operators (space and `|`); scopes match `^[A-Za-z0-9:._~/-]+$` plus the `*` wildcard. In particular a literal `+` in the decoded value (from a `%2B` in the query string) is rejected — use `+` or `%20` to encode a space, never `%2B`.
+
+Extra spaces between groups (leading, trailing, or repeated) are tolerated, since they can easily result from URL formatting and carry no ambiguity — they only ever add required permissions, never remove them. The `|` operator is parsed strictly: `?perm=foo&perm=|bar` is an error, never a way to make `foo` optional.
 
 ## Wildcards
 
-A required scope may contain the * wildcard, which matches any sequence of characters:
+Wildcards work like filenames, with `:` and `/` acting as path separators:
+
+- `*` matches any sequence of characters **within a single segment** (it never crosses a `:` or `/`)
+- `**` matches any sequence of characters, **across separators**
+- Part of a segment can be wildcarded, with required text on either or both sides
 
 ```text
 ?perm=myapp:*
 ```
 
-This matches myapp:read, myapp:write, and any other scope starting with myapp:.
+This matches myapp:read and myapp:write, but **not** myapp:read:all — use `myapp:**` for that. Partial wildcards like `myapp:re*` or `myapp:r*d` match myapp:read. The same applies to path-based scopes: `myapp:path:/api/*` matches myapp:path:/api/clients but not myapp:path:/api/v2/clients — use `myapp:path:/api/**` to span path segments.
 
 ## Effective permissions
 
@@ -68,3 +88,9 @@ Require any scope under myapp:
 ```text
 ?perm=myapp:*
 ```
+
+Require myapp:login and either myapp:read or myapp:write:
+
+```text
+?perm=myapp:login&perm=myapp:read|myapp:write
+```

docs/api/validate.md

@@ -55,10 +55,11 @@ The endpoint always responds with JSON.
 
 If the response includes a Set-Cookie header, the session has been renewed (renewed is true) and you should forward that cookie to the client so the browser updates its expiry. Not forwarding it means the session lifetime is not extended, so the user may need to re-authenticate sooner. Renewals are throttled, so frequent calls usually return renewed: false with no Set-Cookie.
 
-### Failure (401 / 403)
+### Failure (400 / 401 / 403)
 
 | Status | Meaning |
 |---|---|
+| 400 | Malformed perm argument (see [perm](perm.md#syntax-errors)). |
 | 401 | Session missing, expired, or max_age not satisfied. The response body includes auth metadata for the login/reauth iframe. |
 | 403 | Session is valid but one or more requested permissions are missing. |