Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -1886,6 +1886,42 @@ silently — `loadStepUpApprover` refuses it); letting `attestApprover` sign a
what the human saw". `core/tests/store.step-up-approver.mjs`
and `extension/tests/approver-policy.test.mts` pin these.

## A step-up link: the community's request, the person's answer (VTI-LNK-125 – 131)

Someone acting for the person with a key they delegated — their assistant over
`vtc-mcp`, say — can redeem a VTC step-up but never make one. The community
refuses it with a single-use handle beside the inline request, and the
assistant shows the person a `step-up` link. The person pastes it into the
popup (`OpenStepUpLink`, `RUNTIME_STEP_UP_LINK`, extension pages only) or
clicks it on a page (`handleTriggerLink` routes `step-up` away from the
sign-in window). `background.ts::runStepUpLink` drives it:

1. `OFFSCREEN_STEP_UP_FLOW` `read` (`step-up-flows.ts`): only a community the
wallet holds a `didSelfIssued` identity at (`isEntryFor`), or nothing is
sent (`not-in-records`); its DID document resolved and verified;
`auth/step-up/requests/show/0.1` from a fresh key with the handle
(`core/vtc/step-up-handoff.ts`); the returned `request` must be an
approve-request the community signed, to its subject, unexpired, and bound
to the returned operation (`binding-mismatch`); the subject must be one of
the wallet's identities there (`not-the-subject`). `notFound` is
`step-up-gone` (outcome `expired`).
2. The same `check-step-up`, approver prompt (`via: { kind: "link" }`: the
identity from the wallet's own record, the reason labelled as signed by the
community) and `sign-step-up` as `approveStepUp`. There is no page and no
origin pin: the audience is the community the read came from.
3. `answer`: the approve-response, signed by the agent as the subject
(`signTaskAsEntry`, purpose from `proofPurposeForDocumentType`), posted to
the community. Never back to whoever made the link.

The outcome is a notification, since the popup closes when the prompt opens.

**What breaks it:** showing anything from the link or the link's producer as
what is being approved; reading a step-up for a community not in the records;
skipping the binding recompute; answering through anything but the
community's own endpoint; or letting a page send `RUNTIME_STEP_UP_LINK`.
`core/tests/vtc.step-up-handoff.mjs` and `extension/tests/step-up-flows.test.mts`
pin these.

## Repo mechanics worth knowing before you start

- **Task modules are generated here, from `packages/core/trust-tasks.lock`.**
Expand Down
32 changes: 30 additions & 2 deletions packages/core/src/links/trigger-link.ts
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,16 @@ export type TriggerLinkReason =
| "domain-not-linked"
// Local to this reader, outcome `invalid`: the community's verified document
// lists no usable `SignInPortal` service (VTI-LNK-102 names no reason).
| "no-portal-service";
| "no-portal-service"
// `step-up` (VTI-LNK-128 – 130), outcome `invalid`: the contact is not a
// service in the reader's records; its step-up names a subject the reader
// holds no identity for there; or its binding is not the operation's.
| "not-in-records"
| "not-the-subject"
| "binding-mismatch"
// `step-up` (VTI-LNK-129), outcome `expired`: the community answered the
// handle `notFound` — spent, expired, or its step-up already settled.
| "step-up-gone";

/** What the person can do about it (VTI-LNK-021). */
export type TriggerLinkOutcome = "update" | "expired" | "unreachable" | "pass-on" | "invalid";
Expand All @@ -72,6 +81,7 @@ export function outcomeOf(reason: TriggerLinkReason): TriggerLinkOutcome {
case "unsupported-version":
return "update";
case "expired":
case "step-up-gone":
return "expired";
case "no-common-transport":
return "unreachable";
Expand Down Expand Up @@ -384,11 +394,29 @@ export const SIGN_IN_FLOW: TriggerLinkFlowSpec = {
allowsContact: isServiceContact,
};

/**
* `step-up` 0.1, draft (VTI-LNK-125 to 131). The contact is the service that
* refused an operation, and the reader acts only for one already in its own
* records (VTI-LNK-128): the contact rule does not apply, because the service
* qualified when the person added it. So every contact parses, and one that is
* not in the records — a `did:key` among them — is `not-in-records` once the
* flow looks, before anything is sent.
*/
export const STEP_UP_FLOW: TriggerLinkFlowSpec = {
name: "step-up",
base: `${FLOW_REGISTRY_BASE}step-up`,
major: 0,
minors: [1],
draft: true,
requiresExp: true,
allowsContact: () => true,
};

/** The flows this plugin implements, as a reader. `vta-claim` is deliberately
* absent: this wallet does not claim VTAs from a Farm, so such a link is
* `unknown-flow` (outcome `update`). A reader that adds it uses
* {@link isServiceContact} as its `allowsContact` (VTI-LNK-112). */
export const READER_FLOWS: readonly TriggerLinkFlowSpec[] = [SIGN_IN_FLOW];
export const READER_FLOWS: readonly TriggerLinkFlowSpec[] = [SIGN_IN_FLOW, STEP_UP_FLOW];

// ── Results ──────────────────────────────────────────────────────────────────

Expand Down
Loading
Loading