Keysmith milestone 2

This issue spans Keysmith, filecoin-pin, Filecoin Pay Console, and Curio, with specific entry points including core/session/console-url.ts, common/group-key-grant.ts, utils/setupLink.ts, and utils/groupKeyGrant.ts. Start by reading the scope and grant contract described in the issue, then trace one integration point such as accepting scoped grants in common/group-key-grant.ts. Done requires the coordinated scope, gating, share-link, documentation, and end-to-end work listed here; several items need design agreement or depend on external Curio changes.

Milestone 2 of the private data initiative brings in 2 major features over milestone 1:

• Curio gating
• Enabling scopes (aka 'sub groups')

Keysmith is almost ready for this already, just a few things to do:

• Confirm Curio and Keysmith v0.1.0 wire formats for Authorization header match
• Confirm e2e Curio gating with Keysmith 0.1.0 format Authorization header
• Add a helper that turns a delivery into the Authorization: FOC-Grant header (sign request, encodePresentation, base64url). Every tool needs it.
• Add a helper that picks, from a set of grants, the narrowest one that reaches a given scope or piece, so every tool can stash several grants and find the right one the same way.
• Add vectors for the shapes the tools will produce: a scope root to a session key; a session key delegating a piece to a throwaway key; a piece with no foc/scope fetched under a scope grant (refused).
• Share links updated to work with gating (Needs design agreement!)
• Ensure expiry applies only to the root link. Anything else is madness!
• Docs for new read: metadata and Authorization header generation/use
• Hardening for language binding (cherry-pick from #1041 )
  • Strict decoding, low-s signatures and the 48 shared claim vectors matter more once chains get longer.

The scope model is already there. rootClaim and delegateClaim take scope: and piece: nodes and derive their keys; writeTarget(grant, key, scope) labels a piece with foc/scope; keyResolver(key, grant) reads with a scope holding.

The vast majority of work to be done is in filecoin-pin and Filecoin Pay Console to enable scopes. These have a separate epic but FYI, integration points that this epic will not do, but may import work for bug fixes:

Blockers:

[ ] Curio can't read labels inside a CAR. It reads the FEE envelope only at byte 0, but filecoin-pin --encrypt wraps the envelope in an outer UnixFS CAR.
[ ] Restricted pieces fail their proofs. The prove task (tasks/pdpv0/task_prove.go) can't read acl-pieces. This is the open review blocker on curio#1617.
[ ] Share links of restricted uploads break. A link's d= is a bare piece key with no claim chain, and Curio no longer serves gated pieces publicly.

Curio changes related to Keysmith work

The verifier in lib/keysmith already checks scopes: multi-link chains, narrowing at each step, maxDepth, scope: and piece: nodes, NFC-canonical scope paths, and reaches against the envelope's foc/scope. It passes all 48 shared vectors. Gating stays per data set (read: restricted); scopes are checked per piece from its labels.
[ ] Read labels from an envelope inside a CAR (see Blockers).
[ ] Prove from acl-pieces (see Blockers).
[ ] Merge curio#1628: restricted creates and adds of fresh uploads fail without it, because the envelope check reads only the park file.
[ ] Point the interop test at FilOzone/synapse-sdk (it clones a fork today) and run it on the new vectors.

Filecoin-pin changes related to Keysmith work

The largest share of the work: today it asks for, accepts and writes with the whole group key only.
[ ] Ask for a scope: login --scope puts node=scope: in the setup link (core/session/console-url.ts). This needs a new parameter or a widened node contract, agreed with the console.
[ ] Accept scope grants: openGroupKeyGrant refuses any node but keyspace (common/group-key-grant.ts). Accept scope:.
[ ] Hold several grants: the session file keeps one grant today (GROUP_KEY_ID / GROUP_KEY_GRANT). Keep one per scope, add to them with each login --scope without dropping the others, and pick the one that reaches the scope being written or read.
[ ] Write under a scope, session-key mode: pass the scope to writeTarget(opened.grant, opened.key) (common/group-key-grant.ts). Default to the grant's own scope; allow scopes beneath it.
[ ] Write under a scope, owner mode: writeTarget(keys.descriptor, keys.kk) (common/group-key.ts) needs add --scope too.
[ ] Read with a scope grant: the key resolvers already take the grant (group-key-grant.ts, share-link.ts). get and ls should say plainly when a piece is outside the held scope, not fail inside FEE.
[ ] Mark data sets gated: set read: restricted beside foc/enc, foc/ks and foc/kc. Flag or default?
[ ] Fetch gated pieces: download from /download/ with the header helper (see Keysmith), handling 401 and 403.
[ ] Share links for restricted uploads: delegate a piece: claim to the link's throwaway key and carry the chain in the link (see Blockers).
[ ] Allow encrypted login on devnet: login ... encrypt refuses chain 31415926 today (login/run-login.ts), which blocks the e2e tests.

Console (filecoin-pay-explorer) changes related to Keysmith work

The setup page refuses anything but a whole group key on purpose, so an older console never hands out more than a tool asked for. That guard moves to the new contract.
[ ] Accept node=scope:: parseSetupLink returns bad-node for anything but keyspace (utils/setupLink.ts). Widen KeyAgreementRequest.node to match.
[ ] Issue the scoped grant: issueGroupKeyGrant passes node through (utils/groupKeyGrant.ts); rootClaim already derives the scope key from the keyspace key. Set maxDepth to 10 if the owner allows onward delegation, 0 if not (fixed at 0 today).
[ ] Show the scope in the Group key step in plain words ("this tool can read and write photos/2026 only"), let the owner narrow it, and ask "Allow onward delegation?"
[ ] Keep group key selection as it is: chooseGroupKey and the foc/kc check don't change, since scopes sit inside a group key. Update the copy only.
[ ] Tests: scope links, refusing malformed scopes, and a scoped grant opening in filecoin-pin's fixtures.
E2E tests to add on foc-devnet
The current devnet harness covers a whole-keyspace grant from a script and from the console, with 12 checks per run. These join it once the work above lands.
[ ] A scoped grant fetches a piece in its scope, and gets 403 for a sibling scope and for an unscoped piece.
[ ] A session key delegates a piece to a throwaway key; that key fetches only that piece.
[ ] A delegation past maxDepth is refused.
[ ] The console flow with a scope: link.
[ ] A filecoin-pin restricted upload (CAR-wrapped) is accepted, gated, and still proves.
[ ] A share link of a restricted upload opens in the viewer through /download/.