whoami and describe: answer the caller this app actually serves

[korivi-CraftOS]

Two fixes to the same question: what does this app tell a caller it may do, and does it mean it?

1. whoami's 401 carried no hint

whoami answered an uncredentialled caller with a bare 401 while the write path attached a how field to the identical challenge. The two are the same question asked in two places, and only one of them answered it. The default hint is now one constant used by both, and its comment records what that default actually is — an answer only the app's owner can act on, since it names a file on the host.

2. whoami and describe were both lying to an uncredentialled caller

authorize requires a credential for a write and for any operation not declared readOnly, but reaches its anonymous context before the scope check — so on a single-user app an uncredentialled caller reads records perfectly well.

Measured against a running app:

Anonymous caller	Before	After
read a record	200	200
write a record	401	401
whoami	401 — stricter than the surface it reports on	200, credentialId: anonymous
describe access	"full" — claims the write just refused	"read-only"

whoami was stricter than the thing it describes. That hurt the agent doing the right thing: reading your grant before planning work is the documented order, and it stopped at a gate it did not have to, never learning it could have read everything. It now asks authorize the question it exists to answer. The 401 that remains is the honest one — on a multi-user app, or for a write, authorize really would refuse.

describe's over-report was the worse of the two. An agent reads access to know what it may plan, so "full" for a caller that cannot write is not a cosmetic mismatch: it is a plan built on permission that was never held, spent and rejected a round trip later.

A caller without a grant was never scope-checked, so it has no scope set of its own to report. Rather than inventing one, whoami renders the very Access describe uses — one caller cannot be told two different things about itself, because there is only one source.

Nothing is newly permitted

Enforcement is untouched. The write still answers 401; the destructive operation still answers 401. Only the reports changed, from wrong to right.

Verification

• 64/64 conformance. The check that asserted a 401 for any uncredentialled whoami is replaced — on a single-user app that expectation was the bug — by four that pin the truthful answer, the exact scope set (reads + readOnly ops, nothing else), describe's agreement, and the write still being refused.
• New adapter unit test for the multi-user side, which cannot live in conformance: that harness boots one reference app and it is authMode: "none". It covers the 401 standing where it should, the hint surviving, and a credentialled caller still reporting exactly its own grant.
• Verified against a running app — the table above is measured, not reasoned.
• pnpm -r build, pnpm -r typecheck, pnpm -r test clean.

Note

Independent of #4 and does not block it. #4's connect skill documents the current behaviour of a whoami 401; once this merges that paragraph is stale by one sentence, and I can update it in whichever order you merge.

[CraftOS-dev]

No changes needed but need to create a todo to place agent context/prompt/hint to somewhere. To prevent context injected without our knowledge.

[korivi-CraftOS]

Reverted, and the TODO from the review is tracked as #8.

reference/requirements.md and reference/tasks.md in blueprint-python-fastapi are back to the template as shipped — 43 and 2 placeholders. Simulating this merge into main gives 0 conflicts and restores both files, so merging overwrites what reached main by mistake.

One thing beyond a plain revert, flagged because it is a judgement call rather than a mechanical undo: reverting the spec alone puts the suite back to red, since it still expected blueprint-python-fastapi to pass validate. It now sits with the other two starting points, where validate refusing an unauthored spec is validate working:

[ ok ] blueprint-base:              validate refuses (starting point, not a finished app)
[ ok ] blueprint-python-fastapi:    validate refuses (starting point, not a finished app)
[ ok ] blueprint-pocketbase-react:  validate refuses (starting point, not a finished app)
[ ok ] blueprint-react-node:        validate

Its runtime and model are complete; only the spec is deliberately not. If you would rather have the bare revert with no harness change, say so — that leaves CI red until the spec is written, which may be the honest state to sit in.

64/64, all checks green. The same revert is applied to #6 so it cannot reintroduce those files whichever order they merge.

On the inline comment: no code change here, as you said. #8 records it, including the part worth naming — credentialHint is app-supplied and forwarded into the agent's context verbatim, which is the actual injection path. It is written up as a post-#5/#6 change because the constant it concerns is not on main yet.