PP Auth: prove which platform is calling, and let the owner set terms

docs/docs/Post Platform Guide/pp-auth-demonstrator.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 9
+---
+
+# PP Auth demonstrator
+
+Shows platform authentication and domain separation against the live network: real platforms, real certificates from the association, real deployments, and your own eVault.
+
+```bash
+pnpm --filter pp-auth-demo dev
+```
+
+Then open **http://localhost:4310** and sign in with your wallet. It needs `PPA_AWARENESS_API_KEY` (or `AWARENESS_API_KEY`) to see the network, and `PUBLIC_REGISTRY_URL` to resolve eVaults.
+
+Nothing is seeded. If the platforms page is empty, nothing has been deployed or certified yet — which is a true statement about the network rather than a failure of the app.
+
+## Platforms
+
+Every platform with a deployment or a certification decision, read live. Under each are the deployments actually running it, with the release and commit they were built from.
+
+**Check it** verifies that deployment's chain of trust, from scratch, against records anyone can read:
+
+| Link | Where the evidence comes from |
+|---|---|
+| Possession | the deployment itself — see below |
+| Deployment authorised | the wallet signature on the deployment's key document, resolved through the registry |
+| Bundle integrity | the hashes covered by that same signature |
+| Version identity | UUIDv5 arithmetic over the platform eName and version |
+| Release authorship | the release proof in the platform's own profile, and its registry key-binding certificate |
+| Accreditation | the association's ES256 certificate for that exact version |
+
+Five of the six are checked by reading. **Possession is not** — the deployment's private key never leaves the deployment, so a reader cannot answer a challenge on its behalf. That link reports "not attempted" rather than pretending it failed a check that was never made.
+
+If you hold the key — because you are the person who made that deployment — paste it and the challenge is signed for real. It is kept in memory for that process only: never written to disk, never logged, gone on restart. A wrong key produces a genuine signature that genuinely fails.
+
+## Your data
+
+Your own eVault records, grouped by the domain each schema declares. That grouping is what a certificate is written against, so it is also what decides who sees what.
+
+The table shows every certified platform against every kind of data you hold, decided by the real certificate's domains and your real signed terms, using the same `authorize` an eVault would call. A platform certified for `social`, `finance` and `media` is allowed those and refused everything else — with the reason spelled out. It cannot reach your messages or your files, and nothing it presents will change that.
+
+## Permissions
+
+Being certified for a kind of data is not permission to do anything with it. This tab is where that is settled.
+
+The domain list is the whole published vocabulary, not just what a platform was certified for — the domains it has no business with are listed too, marked as such, because asking for one and watching the certificate refuse it is the case worth seeing.
+
+Grants are managed by the platform through `POST /api/grants`, not set by hand here — the page shows what happens under them. Each change writes an `AccessGrant` into the owner's eVault as a new revision; clearing both operations withdraws the grant rather than deleting it, so the record shows access was taken away rather than never given.
+
+```bash
+curl -X POST http://localhost:4310/api/grants \
+  -H 'Content-Type: application/json' \
+  -d '{"platformEname":"@…","domain":"social","operations":["read"]}'
+```
+
+**Deployment keys go in here, before you try anything.** Possession is the one link a reader cannot establish by looking, so whether the key is present decides what a check can even mean. Enter it and the deployment can answer a challenge for real; leave it out and every request stops at the handshake, which is the correct outcome.
+
+**Try a request** then runs one all the way through — a named deployment, an operation, a domain — and reports which of the three gates decided.
+
+A permitted read is not a verdict: it goes to the eVault and the records it returns are rendered underneath. A refused one fetches nothing, and says so — the eVault is never asked. A permitted write really writes, with text you supply, into a schema belonging to that domain, and then reads the domain back so you can see it landed.
+
+Turn off write and a write is refused while a read still succeeds; withdraw the grant and the refusal changes from "has not been given permission" to "has been withdrawn".
+
+## Your terms
+
+The association says what a platform was found to be; you decide what that is worth. Set the minimum level and any domain refused outright. The reputation service is named in what you sign but is not a choice: there is one on the network today, so asking you to type its address would only be a way to get it wrong.
+
+Signing goes to your wallet. The signing session id **is** the canonical payload of the statement, so what the wallet signs is exactly the digest of your terms — the signature then verifies against the statement on its own, without anyone trusting this app. The terms are published into your own eVault as an `Access Policy` record, world-readable, and the signature is checked again before the write.
+
+Your terms can only narrow a certificate, never widen it. Permitting `finance` does not let a platform reach finance data it was not certified for.
+
+## See also
+
+- [Platform Authentication](/docs/W3DS%20Protocol/Platform-Authentication)
+- [Access Policy](/docs/W3DS%20Basics/Access-Policy)

docs/docs/Post Platform Guide/pp-auth.md

@@ -0,0 +1,116 @@
+---
+sidebar_position: 10
+---
+
+# Authenticating your platform
+
+Your deployment proves which release it is running, and the eVault decides what that release may touch. This page is the integration.
+
+For the mechanism itself see [Platform Authentication](/docs/W3DS%20Protocol/Platform-Authentication).
+
+## Install
+
+```bash
+pnpm add @metastate-foundation/auth
+```
+
+Both halves ship in one package. Deployments import the signer, verifiers import the verifier; nothing stops you doing both, which is what the demonstrator does.
+
+## What your deployment needs
+
+GitW3 produces all of it when you deploy a release. None of it is secret except the private key, which never leaves your process.
+
+```ts
+import type { DeploymentIdentity } from "@metastate-foundation/auth/platform";
+
+const identity: DeploymentIdentity = {
+  privateKey: process.env.DEPLOYMENT_PRIVATE_KEY!,  // PKCS#8, base64
+  evidence: {
+    deploymentEname, deploymentName, environment,
+    deployerEname, platformEname, versionEname,
+    version, releaseTag, commitSha, publicKey,
+    deploymentKeyDocument,      // binding document, bundle-signed
+    softwareVersionDocument,    // binding document, same signature
+    accreditationJws,           // the association's certificate
+    issuerJwksUri,
+    submissionProof,            // the release proof the association reviewed
+  },
+};
+```
+
+Store the private key the way you store any other deployment secret. If it leaks, the holder can authenticate as your deployment until the deployer revokes the key — it is the whole of the possession proof.
+
+## Authenticating
+
+```ts
+import { authenticate } from "@metastate-foundation/auth/platform";
+
+const result = await authenticate(identity, "https://vault.example");
+```
+
+That fetches a challenge, signs it, and posts the answer. If you want the two steps yourself — to add retries, or to talk to something other than HTTP — use `answerChallenge(identity, challenge)` and send the response however you like.
+
+## Verifying, if you are the eVault
+
+```ts
+import {
+  createChallengeStore,
+  verifyHandshake,
+  authorize,
+} from "@metastate-foundation/auth/platform";
+
+const challenges = createChallengeStore();          // module scope, not per request
+
+// POST /pp-auth/challenge
+const challenge = challenges.issue(ownerEname);
+
+// POST /pp-auth/verify
+const chain = await verifyHandshake(response, {
+  audience: ownerEname,
+  registryBaseUrl: process.env.PUBLIC_REGISTRY_URL!,
+  store: challenges,
+});
+
+if (!chain.ok) {
+  // chain.links carries all six with a plain-English detail on each.
+  return refuse(chain.links.find((link) => !link.ok));
+}
+```
+
+`chain.claim` is what you learned: platform, deployment, version, level, and the domains it may use.
+
+Then the owner's terms, for each record touched:
+
+```ts
+const decision = authorize(policy, {
+  claim: chain.claim,
+  domain: schema.domain,            // the domain the record's ontology declares
+  reputation: score ? { engine, score } : null,
+});
+
+if (!decision.allowed) return refuse(decision.reason);
+```
+
+`decision.reason` is written to be shown to a person. `decision.code` is for your logs.
+
+Hold the challenge store at module scope. Issuing from one instance and redeeming in another rejects every legitimate handshake, and under Vite's dev server a module evaluated twice will do exactly that.
+
+## Injection points
+
+Three things are injectable, all defaulting to the ordinary behaviour:
+
+- `verifyWalletSignature` — how a wallet signature is checked. Defaults to `signature-validator` against your registry.
+- `resolveJwks` — how a JWKS URI becomes keys. Defaults to a cached remote fetch. Supply your own to pin a key set or to run offline.
+- `now` — the clock, for testing time-dependent behaviour.
+
+## Testing your integration
+
+`@metastate-foundation/auth/platform/scenario` mints a complete, self-consistent chain from keys it generates, so you can exercise your verifier without a wallet, a registry or a live association:
+
+```ts
+import { createTrustRoots, mintDeployment } from "@metastate-foundation/auth/platform/scenario";
+```
+
+Everything it produces is genuinely signed and genuinely verified. What differs is the root: the keys standing in for the deployer, the registry and the association are local. **Never configure a production verifier with roots from this module** — a chain that verifies against them proves your code works, not that a platform is trustworthy.
+
+The [demonstrator](/docs/Post%20Platform%20Guide/pp-auth-demonstrator) is built on it and is the fastest way to see the whole thing move.

docs/docs/W3DS Basics/Access-Policy.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 6
+---
+
+# Access Policy
+
+Certification tells you what a platform was found to be. It does not tell you whether you want to deal with it. That is the eVault owner's decision, and an **access policy** is where they write it down.
+
+It is a signed statement rather than a stored setting, so it travels with the owner and anyone can check it — the eVault enforcing it, a platform working out whether it is even worth asking, or the owner auditing what they agreed to months later.
+
+## What an owner sets
+
+| Term | Meaning |
+|---|---|
+| `minimumLevel` | The weakest certification level they will deal with. A platform certified below it is refused whatever its certificate grants. |
+| `reputationEngine` | Whose reputation scores they accept, as an eName or host. Blank means reputation is not consulted at all. Today the network runs one service, so applications may reasonably fix this rather than ask. |
+| `minimumReputation` | The score that engine must report for the platform. Null means no threshold, which is the common case. |
+| `allowedDomains` | Null means "whatever the certificate grants" — the ordinary case. A list narrows it further. |
+| `deniedDomains` | Refused outright, overriding both the certificate and the allow list. |
+
+Naming the engine matters. A score is only meaningful relative to how it was calculated, so the owner elects which calculation they accept rather than inheriting whichever engine a platform happens to cite. A score from an engine the owner did not name counts as no score at all.
+
+## A policy can only narrow
+
+An owner permitting `finance` does not let a social platform reach finance data. The certificate gate runs first and independently: if `finance` is not in what the association granted the release, nothing in the owner's policy can put it there.
+
+This ordering is the point. The owner's terms are a second lock, not a master key.
+
+## The statement
+
+```json
+{
+  "subject": "@849c0221-6f3f-55f9-95f0-f3b0d2b3092f",
+  "minimumLevel": "L3",
+  "reputationEngine": "@ereputation.w3ds",
+  "minimumReputation": 40,
+  "allowedDomains": null,
+  "deniedDomains": ["health"],
+  "issuedAt": "2026-08-30T16:04:11.230Z",
+  "nonce": "0f1c…"
+}
+```
+
+Signed by the owner's wallet over `w3ds:access-policy:v1:` + base64url(sha256(canonical statement)). The signer must be the subject: a policy signed by anyone else is somebody setting terms on a vault that is not theirs, and is rejected.
+
+The newest statement for a subject is the one in force. An owner who has never set one is treated as requiring **L2** — the lowest level the framework issues to a release whose responsible people are identified at all.
+
+Published as the `Access Policy` ontology (`c7a41f6d-95b8-4e2a-9c33-8f0d1b6e4a72`), domain `governance`.
+
+## Permissions are a separate question
+
+A policy says which platforms you will deal with. It does not say what they may *do* — reading your posts is not the same as writing to them.
+
+That is what an [`AccessGrant`](https://github.com/MetaState-Prototype-Project/prototype/blob/main/services/ontology/schemas/accessGrant.json) is for: a grantee, a resource, and permissions written as `resource:Action` (`social:Read`, `finance:Write`). Grants are **deny by default** — a platform that is certified for a domain and permitted by your policy still needs a grant covering the operation it is attempting.
+
+Grants are append-only. Changing what a platform may do writes a new revision rather than editing the old record, and withdrawing access marks the grant revoked while keeping the permissions it used to carry. So "your access was withdrawn" and "you never had access" stay distinguishable, which matters when explaining a refusal to someone.
+
+The three gates run in order, and each can only narrow the one before it:
+
+1. **The certificate** — was this release assessed for this domain?
+2. **Your policy** — will you deal with this platform at all?
+3. **The grants** — may it do this particular thing?
+
+A grant cannot widen a certificate. Permitting `health:Read` to a platform never certified for `health` changes nothing.
+
+## See also
+
+- [Platform Authentication](/docs/W3DS%20Protocol/Platform-Authentication) — how a platform proves which release it is running

docs/docs/W3DS Basics/Links.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Links