@visa/cli 4.1.0-rc.287 → 4.1.0-rc.288

package/README.md

@@ -35,6 +35,16 @@ iwr -useb https://app.visacli.sh/install.ps1 | iex
 
 Node.js 20+ is required. macOS, Windows, and Linux are supported for the v4 wallet flow.
 
+### Managed runtime convergence
+
+The RC package also installs `visa-runtime-converge` for supervisor-owned
+OpenClaw/Hermes/Telegram deployments. A scheduled invocation resolves the
+preview server's recommended exact RC, stages and integrity-checks it, restarts
+through the configured supervisor, verifies the loaded version/environment, and
+rolls back a failed activation. It never updates an interactive owner-managed
+installation. Configuration and readiness contracts are documented in
+[`packages/visa-cli-openclaw/RUNTIMES.md`](https://github.com/Visa-Crypto-Labs/Visa-mono/blob/staging/packages/visa-cli-openclaw/RUNTIMES.md).
+
 ## MCP setup
 
 The fastest path is to let the CLI write the client config for you:
@@ -389,6 +399,15 @@ certificate, delegation, Gate authorization and native key binding. The selected
 native profile serves actual TAP consumers; unavailable custody or invalid selected
 metadata fails closed. Wallet/card keys and payment authority remain separate.
 
+`--agent` accepts either a locally paired agent or the stable UUID of a protected
+agent created by `visa agent enroll-protected`; the latter has no Auth-paired record
+and resolves its owner root from the independently claimed selection. The device
+ceremonies (`connect-device`, `renew`, `resume`, `revoke --purpose tap`) travel the
+public identity-device relay with native possession proofs, so a missing or expired
+`visa agent login` never blocks them; the owner approval and owner revocation pages
+remain required. Hosted purposes (`card:vic`, `wallet:x402`, hosted `tap`, `subway`)
+still need a locally paired agent and its Auth session.
+
 `visa agent keychain renew --agent <name-or-id> --purpose tap` creates an independently
 addressed successor for the same runtime and opens the owner review page. Both keys
 survive interruption. `visa agent keychain resume --agent <name-or-id>` resumes the

package/dist/checkout-engine/vgs-gateway/server-mint-client.d.ts

@@ -1,3 +1,4 @@
+import { type KeyObject } from 'node:crypto';
 import type { VgsCheckoutTarget, VgsPaymentCredential } from '../vgs-live-instrument.js';
 export type ServerMintDeps = {
     /** Injectable for tests — defaults to global fetch. */
@@ -136,3 +137,17 @@ export declare function serverPostConfirmation(base: string, mintToken: string,
 }, deps?: ServerMintDeps): Promise<{
     ok: true;
 }>;
+/** One exact protected attempt. Caller retains its delivery KeyObject across
+ * retries; it is never serialized into a request, receipt, log, or agent context. */
+/** Pins are installed with the checkout deployment, never supplied by Auth or the response. */
+export interface ProtectedCardPins {
+    executor: KeyObject;
+    issuer: KeyObject;
+}
+export declare function serverFetchProtectedCryptogram(base: string, input: {
+    financialAdmission: string;
+    request: unknown;
+    requestHash: string;
+    deliveryKey: KeyObject;
+    pins: ProtectedCardPins;
+}, deps?: ServerMintDeps): Promise<VgsPaymentCredential>;

package/dist/checkout-engine/vgs-gateway/server-mint-client.js

@@ -1,3 +1,4 @@
+import { createDecipheriv, createHash, verify, createPublicKey, diffieHellman, hkdfSync, } from 'node:crypto';
 // Server-side mint client (Phase 1) — the checkout runner mints the payment
 // credential by calling the verify-web deployment's gateway routes with a
 // short-lived, purpose-scoped MINT TOKEN, instead of holding the shared VGS
@@ -330,3 +331,163 @@ export async function serverPostConfirmation(base, mintToken, input, deps = {})
         throw new Error(`server confirmation failed (${res.status}): ${await routeError(res)}`);
     return { ok: true };
 }
+function cardEvidence(token, key, typ, fields) {
+    const fail = () => {
+        throw new Error('protected_card_evidence_invalid');
+    };
+    if (key.type !== 'public' ||
+        key.asymmetricKeyType !== 'ed25519' ||
+        typeof token !== 'string' ||
+        token.length > 16384)
+        return fail();
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return fail();
+    const jwk = key.export({ format: 'jwk' });
+    const kid = createHash('sha256')
+        .update(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x }))
+        .digest('base64url');
+    const header = JSON.parse(Buffer.from(parts[0], 'base64url').toString());
+    const claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    if (!header ||
+        Object.keys(header).sort().join(',') !== 'alg,kid,typ' ||
+        header.alg !== 'EdDSA' ||
+        header.typ !== typ ||
+        header.kid !== kid ||
+        !claims ||
+        Object.keys(claims).sort().join(',') !== fields.sort().join(',') ||
+        claims.v !== 1 ||
+        typeof claims.jti !== 'string' ||
+        !claims.jti ||
+        !Number.isSafeInteger(claims.iat) ||
+        !verify(null, Buffer.from(parts.slice(0, 2).join('.')), key, Buffer.from(parts[2], 'base64url')))
+        return fail();
+    return claims;
+}
+export async function serverFetchProtectedCryptogram(base, input, deps = {}) {
+    const hash = Buffer.from(input.requestHash, 'base64url');
+    if (hash.length !== 32 ||
+        hash.toString('base64url') !== input.requestHash ||
+        input.deliveryKey.type !== 'private' ||
+        input.deliveryKey.asymmetricKeyType !== 'x25519')
+        throw new Error('protected_card_delivery_key_invalid');
+    const response = await (deps.fetchImpl ?? fetch)(`${stripTrailingSlashes(base)}/api/vgs/payment-cryptogram`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-visa-card-protected': 'v1' },
+        body: JSON.stringify({
+            financialAdmission: input.financialAdmission,
+            request: input.request,
+        }),
+        redirect: 'error',
+    });
+    if (response.status === 202)
+        throw new Error('protected_card_recovery_pending');
+    if (!response.ok)
+        throw new Error(`protected_card_refused_${response.status}`);
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('protected_card_response_invalid');
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            size += part.value.byteLength;
+            if (size > 65536) {
+                await reader.cancel();
+                throw new Error('protected_card_response_invalid');
+            }
+            chunks.push(part.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const envelope = JSON.parse(Buffer.concat(chunks).toString());
+    if (!envelope ||
+        Object.keys(envelope).sort().join(',') !==
+            'acknowledgement,ciphertext,ephemeralPublicJwk,iv,outcome,tag,v' ||
+        envelope.v !== 1)
+        throw new Error('protected_card_response_invalid');
+    const coordinates = [
+        'v',
+        'aud',
+        'jti',
+        'attemptId',
+        'requestHash',
+        'admissionId',
+        'issuanceGeneration',
+        'iat',
+    ];
+    const outcome = cardEvidence(envelope.outcome, input.pins.executor, 'visa-card-delivery-outcome+jwt', [...coordinates, 'outcome', 'providerRef', 'credentialSha256']);
+    const ack = cardEvidence(envelope.acknowledgement, input.pins.issuer, 'visa-card-delivery-state+jwt', [...coordinates, 'action', 'outcomeHash', 'exp']);
+    const permit = JSON.parse(Buffer.from(input.financialAdmission.split('.')[1], 'base64url').toString());
+    const now = Math.floor(Date.now() / 1000);
+    if (outcome.aud !== 'urn:visa:authority:card-outcome' ||
+        outcome.outcome !== 'credential_observed' ||
+        outcome.requestHash !== input.requestHash ||
+        outcome.attemptId !== permit.attemptId ||
+        outcome.admissionId !== permit.jti ||
+        outcome.issuanceGeneration !== permit.issuanceGeneration ||
+        ack.aud !== 'urn:visa:executor:card-vic' ||
+        ack.action !== 'recover_only' ||
+        ack.requestHash !== outcome.requestHash ||
+        ack.attemptId !== outcome.attemptId ||
+        ack.admissionId !== outcome.admissionId ||
+        ack.issuanceGeneration !== outcome.issuanceGeneration ||
+        !Number.isSafeInteger(ack.exp) ||
+        ack.exp <= now ||
+        ack.iat > now + 5 ||
+        ack.exp <= ack.iat ||
+        ack.exp - ack.iat > 60 ||
+        ack.outcomeHash !== createHash('sha256').update(envelope.outcome).digest('base64url'))
+        throw new Error('protected_card_evidence_invalid');
+    const jwk = envelope.ephemeralPublicJwk;
+    if (!jwk ||
+        Object.keys(jwk).sort().join(',') !== 'crv,kty,x' ||
+        jwk.kty !== 'OKP' ||
+        jwk.crv !== 'X25519')
+        throw new Error('protected_card_response_invalid');
+    const decode = (value, size) => {
+        if (typeof value !== 'string')
+            throw new Error('protected_card_response_invalid');
+        const decoded = Buffer.from(value, 'base64url');
+        if (decoded.toString('base64url') !== value || (size !== undefined && decoded.length !== size))
+            throw new Error('protected_card_response_invalid');
+        return decoded;
+    };
+    decode(jwk.x, 32);
+    const shared = diffieHellman({
+        privateKey: input.deliveryKey,
+        publicKey: createPublicKey({ key: jwk, format: 'jwk' }),
+    });
+    const key = Buffer.from(hkdfSync('sha256', shared, hash, 'visa-card-delivery-v1', 32));
+    shared.fill(0);
+    let clear;
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, decode(envelope.iv, 12));
+        decipher.setAAD(Buffer.from(input.requestHash));
+        decipher.setAuthTag(decode(envelope.tag, 16));
+        clear = Buffer.concat([decipher.update(decode(envelope.ciphertext)), decipher.final()]);
+        if (createHash('sha256').update(clear).digest('base64url') !== outcome.credentialSha256)
+            throw new Error('protected_card_credential_invalid');
+        const credential = JSON.parse(clear.toString());
+        if (!credential ||
+            typeof credential.networkToken !== 'string' ||
+            typeof credential.cryptogramValue !== 'string' ||
+            !Number.isInteger(credential.expMonth) ||
+            credential.expMonth < 1 ||
+            credential.expMonth > 12 ||
+            !Number.isInteger(credential.expYear) ||
+            credential.expYear < 2000 ||
+            typeof credential.cryptogramType !== 'string')
+            throw new Error('protected_card_credential_invalid');
+        return credential;
+    }
+    finally {
+        key.fill(0);
+        clear?.fill(0);
+    }
+}