@panaversity/ksor 0.0.45 → 0.0.46

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @panaversity/ksor
 
+## 0.0.46
+
+### Patch Changes
+
+- a28fac9: **The Auth0 recipe now names the trap that costs the afternoon it warns about.**
+  Walked end to end against a live Auth0 tenant and a deployed door for the first
+  time (2026-08-26), and the recipe was right about what to type and silent about
+  the two things that actually go wrong.
+
+  The API **Identifier** must equal `KSOR_MCP_RESOURCE_URL` character for
+  character, `/mcp` path included — and **Auth0 does not let you edit it after the
+  API is created**, so a wrong one is fixed by making a new API, not by correcting
+  the field. Neither fact was written down.
+
+  Two Auth0 errors now have a table, because both arrive as a failed token request
+  and they mean opposite things: `Service not enabled within domain` is no API
+  with that Identifier, while `Client "…" is not authorized to access resource
+server` means the Identifier is right and the grant from step 5 is missing.
+  Moving from the first to the second is progress.
+
+  And "Verify it" gains a step 0: ask the PROVIDER for a token before touching the
+  door. Half of these failures never reach ksor, and one `curl` at the token
+  endpoint separates the halves — which is how this diagnosis was actually made,
+  after several rounds of reasoning about dashboard toggles that turned out not to
+  be the cause.
+
+  **And it now says you need more than one Application.** The recipe never
+  mentioned the site's own sign-in control, never said its Application is a
+  different TYPE from an assistant's, and never said the two cannot be the same
+  registration — a public client with no secret and a confidential client that
+  sends one are different things, and using one for both returns a bare `401` at
+  the token endpoint that names nothing. A table at the top of the recipe now
+  gives one row per caller: what type, what token-endpoint auth, what callback,
+  and whether it needs the grant from step 5.
+
 ## 0.0.45
 
 ### Patch Changes

package/docs/authorization.md

@@ -298,6 +298,25 @@ Nothing else in this recipe makes sense until that lands. You are not building
 an API; you are describing the one you already have so Auth0 can mint tokens
 aimed at it.
 
+**You will need MORE THAN ONE Application, and they are different types.** This
+is the single thing most likely to waste your afternoon, because one application
+configured for one caller returns a plain `401` to the other with nothing
+naming the mismatch (found the hard way, 2026-08-26). One API, one caller per
+row:
+
+| The caller                                        | Auth0 Application Type      | Token endpoint auth        | Callback                                                            | Needs step 5 |
+| ------------------------------------------------- | --------------------------- | -------------------------- | ------------------------------------------------------------------- | ------------ |
+| the SITE's sign-in control (`NEXT_PUBLIC_KSOR_*`) | **Single Page Application** | **None** — PKCE, no secret | `https://your-site/auth/callback`                                   | no           |
+| an assistant a person logs into (Claude, an IDE)  | **Regular Web Application** | client secret              | the assistant's own, e.g. `https://claude.ai/api/mcp/auth_callback` | **yes**      |
+| a script, worker or backend agent                 | **Machine to Machine**      | client secret              | none                                                                | **yes**      |
+
+The site row is a different flow and not really part of this page: it requests
+`openid profile email` and **no audience**, so it never touches your API and
+needs no grant. It is here only so you do not try to serve it and an assistant
+from one application — a public client with no secret and a confidential client
+that sends one cannot be the same registration, and the failure is a `401` at
+the token endpoint that says nothing about why.
+
 ### 1. Describe the door
 
 **Applications → APIs → Create API.** The **Identifier** you type becomes the
@@ -309,6 +328,24 @@ Name:       my-record
 Identifier: https://your-host.example.com/mcp
 ```
 
+**Type the whole URL, `/mcp` included, and get it right the first time.** The
+Identifier must equal `KSOR_MCP_RESOURCE_URL` character for character — the host
+alone is not enough, because that is not what the door will compare against. And
+**Auth0 does not let you edit an Identifier after the API is created**: a wrong
+one is fixed by creating a NEW API with the right string and granting your
+application access to that one instead.
+
+Two Auth0 errors tell you exactly where you are, and they are easy to confuse
+because both arrive as a failed token request (reported by an adopter,
+2026-08-26):
+
+| Auth0 says                                                               | Means                                                                                      |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `Service not enabled within domain: https://…/mcp`                       | **no API has that Identifier.** Yours was created with a different string — make a new one |
+| `Client "…" is not authorized to access resource server "https://…/mcp"` | the API is right and the **grant** is missing — step 5                                     |
+
+Moving from the first message to the second is progress, not a new problem.
+
 Creating it also creates a machine-to-machine **test application** named
 `<API> (Test Application)`. That is your first caller — you do not need to make
 one.
@@ -447,9 +484,25 @@ Use the commands below when it did NOT work, or when the caller is a script
 rather than a person. A token from your provider proves the provider works; it
 does not prove the door does. Both halves matter, and the refusal matters more.
 
+**0. Ask the provider for a token FIRST, before you touch the door.** Half the
+failures on this page never reach ksor at all, and this one command separates
+the two halves in a second:
+
+```sh
+curl -s -X POST https://YOUR_TENANT.us.auth0.com/oauth/token \
+  -H 'content-type: application/json' \
+  -d '{"grant_type":"client_credentials","client_id":"…","client_secret":"…",
+       "audience":"https://your-host.example.com/mcp"}'
+```
+
+An `error` here is the PROVIDER refusing, and no amount of ksor configuration
+will change it — see the table in step 1 for what each message means. An
+`access_token` here means the provider works, and anything still failing is the
+door or the token's contents, which is what the rest of this section is for.
+
 **1. Decode the token before using it.** This is the single most useful
-debugging step on this page, because a valid token audienced at the wrong thing
-looks identical to a broken one:
+debugging step once you have one, because a valid token audienced at the wrong
+thing looks identical to a broken one:
 
 ```sh
 echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq '{iss, aud, exp}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.45",
+  "version": "0.0.46",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",