Support Link Pay Token checkout in vault card commands

[rgarcia]

Summary

Brings the vault card commands in line with the Link Pay Token vault API (kernel/kernel#3950).

• Authorize at checkout: items invoke <vault> <key> authorize takes optional --browser-id and --page-url, sent as browser_id and page_url. The CLI rejects one without the other, a blank browser ID, a non-https or credential-bearing page URL, and either flag on any other operation, all before calling the API. Without the flags, authorize still sends {"type":"authorize"}.
• Authorize errors: Link card authorize failures print the API's code and message plus a recovery step. Checkout inspection errors (page_not_found, ambiguous_page, browser_not_found, browser_unavailable, destination_denied, timeout, browser_error) say no payment request was made, to fix the tab and authorize again, and to fall back to a virtual card if inspection keeps failing. invalid_request covers the virtual card limit; 429 says wait and authorize again.
• Fill without fields: card fills may omit fields (a Link Pay Token fill requires this); the request then omits fields, and the item's fill description and API validation decide. Credential fills still require fields client-side. A field-less result ("fields":[]) is accepted for completed, failed, and unknown, and human output says to submit the checkout yourself.
• Card update: unchanged PATCH path, now tested for success and for the 409 a Link card returns after it is authorized at a checkout. Its help says it works only before a Link card is authorized at a checkout; after that, delete and recreate.
• Help text: one shared Link checkout flow (linkCardFlowHelp) appears in vaults, wallets create, cards create, cards update, and items invoke, in the order reach checkout → create card → authorize with browser ID and page URL → share approval URL → wait for fill → fill → submit yourself. Removed or reworded text that conflicted with it (browser attached after card creation, "authorize takes no parameters", unconditional "checkout cards can be edited between authorizations", provider-assigned domains for Link, bare "never retry"). README's Link section follows the same flow.
• Runtime output: the wallet's server-generated description is shown in human and JSON output. items get on a requested Link card suggests authorize --browser-id ... --page-url .... Link card guidance now gives recovery steps instead of "never retry automatically".

SDK

Bumps github.com/kernel/kernel-go-sdk to v0.126.0.

Testing

• go vet ./... and go test ./... pass.
• golangci-lint run: no findings on changed lines (pre-existing findings elsewhere are unchanged).
• New tests in cmd/vaults_link_test.go cover: the shared flow appearing in every command's help and its step order; retired wording; the authorize request body with and without checkout flags; client-side flag validation (no API call); error guidance for each authorize error code; Pay Token fill with no fields in the request and field-less results; credential fill still requiring fields; Link card update success and 409; and wallet description output.
• Not run against the production API.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	golang/​github.com/​kernel/​kernel-go-sdk@​v0.123.1-0.20261012183001-8e8343ff3131 ⏵ v0.126.0	+1

View full report

[cursor]

Stale Bugbot comment from a previous run.

[bmsaadat]

thanks, the authorize flags, error mapping and field-less fill all line up with the API, and go vet / go test ./... pass locally on v0.126.0. requesting changes for one wording fix, plus one API bug this surfaces:

1. user approval before authorize (cmd/vaults_link.go step 3, README.md): the flow no longer says to get the user's approval before authorizing, and the README line "After explicit user approval, authorize only if the item advertises it" was removed. the API's Link authorize description still opens with "Use once the user has approved this purchase", so could we add that back to step 3 and the README?
2. unattached browser returns an opaque 500 (API, from #3950): if the browser isn't attached to the vault (or is deleted, or an unleased pool instance), vaultFillSessionOnce returns a fillUnavailableError, which linkCardCheckoutError doesn't match (errors.As on vaultfill.Error), so authorize returns 500 provider_error "failed to perform item operation". the CLI's default advice then says to re-get the item and follow its operations, which leads straight back to authorize. probably best fixed in the API (map it to browser_unavailable); until then a CLI hint like "check that the browser was created with --vault" on a 5xx with checkout flags would help.

optional:

• --page-url validation differs from the API's pattern both ways (e.g. a space in the path or * in the host passes here but the API rejects it); reusing ^https://[^/?#@*\s]+(?:[/?#][^\s]*)?$ would line them up.
• the Link 429 advice drops Retry-After, which the Kernel path shows.
• a network error on Link authorize now hides the underlying cause (kernelVaultTransportError.Error() prints only the generic message).
• Kernel cards no longer get the client-side check for missing fill fields or checkout flags (the API still rejects both with a 400).
• restart_verification --browser-id says to pass inputs with --params, but that operation takes none.

[rgarcia]

Thanks. Addressed in 3e75f4c:

1. User approval before authorize: step 3 of the shared Link flow now reads "once the user has approved this purchase, authorize with items invoke …", and README step 4 says "Once the user has approved this purchase, and only when the item advertises authorize, …".
2. Unattached browser 500: this PR doesn't change the API. In the CLI, a 5xx on a Link authorize that carried --browser-id/--page-url now prints: "if the browser was not created with --vault for this vault, was deleted, or is a pool browser that is not leased, checkout inspection cannot run: create a browser with --vault, open the checkout in it, and authorize again with that browser's session id. otherwise re-get the item and follow its advertised operations". Without the flags, the default advice is unchanged. I'll raise the API fix (map fillUnavailableError to browser_unavailable in linkCardCheckoutError) separately.

Optional items, all done:

• --page-url is now checked against the API's pattern ^https://[^/?#@*\s]+(?:[/?#][^\s]*)?$ (tests cover a space in the path and * in the host).
• Link 429 advice uses Retry-After through a retryAfterWait helper shared with the Kernel path.
• A network error on Link authorize now includes the underlying cause: authorize result unavailable (<cause>); ….
• Fill without fields and the checkout flags are rejected before the POST for anything but a Link card, including Kernel cards.
• restart_verification --browser-id now says only "--browser-id and --page-url are only supported for authorize"; the --params hint appears only for operations that take parameters.

go vet ./... and go test ./... pass.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3e75f4c. Configure here.}