@visa/cli 4.1.0-rc.25 → 4.1.0-rc.3

package/dist/checkout-engine/vgs-live-instrument.js

@@ -1,252 +0,0 @@
-/**
- * Our fail-closed freshness bound, matching the runner's 15-minute checkout
- * review window — NOT a claim about VGS's actual assurance TTL (unpublished).
- * The only proven-working configuration mints the intent right after the
- * ceremony; anything older is refused before an intent is created.
- */
-export const PURCHASE_ASSURANCE_MAX_AGE_MS = 15 * 60 * 1000;
-/** Tolerated forward clock skew on `mintedAt` before it is treated as invalid. */
-const PURCHASE_ASSURANCE_MAX_SKEW_MS = 2 * 60 * 1000;
-export function decimalToMinor(value) {
-    // JSON files routinely carry a number where the contract says decimal string
-    // ("transactionAmount": 5): refuse non-strings HERE so every caller surfaces
-    // its scoped invalid/mismatch remedy instead of a raw TypeError crash.
-    if (typeof value !== 'string')
-        return null;
-    if (!/^\d+(\.\d{1,2})?$/.test(value))
-        return null;
-    const [whole, fraction = ''] = value.split('.');
-    const minor = Number(whole) * 100 + Number(fraction.padEnd(2, '0'));
-    return Number.isSafeInteger(minor) ? minor : null;
-}
-function validateTarget(reference, ctx) {
-    if (typeof reference.merchantName !== 'string' ||
-        typeof reference.merchantCountryCode !== 'string' ||
-        !reference.merchantName.trim() ||
-        !/^[A-Z]{2}$/.test(reference.merchantCountryCode)) {
-        throw new Error('VGS checkout reference merchant name/country is invalid');
-    }
-    let referenceHost;
-    try {
-        referenceHost = new URL(reference.merchantUrl).hostname;
-    }
-    catch {
-        throw new Error('VGS checkout reference merchant URL is invalid');
-    }
-    if (referenceHost !== ctx.merchantHost) {
-        throw new Error(`VGS credential merchant mismatch: ${referenceHost} vs ${ctx.merchantHost}`);
-    }
-    const amountMinor = decimalToMinor(reference.transactionAmount);
-    if (amountMinor === null)
-        throw new Error('VGS checkout reference amount is invalid');
-    if (amountMinor !== ctx.amountMinor) {
-        throw new Error(`VGS credential amount mismatch: ${amountMinor} vs ${ctx.amountMinor} minor units`);
-    }
-    // String() so a JSON-number currency (840) mismatches with a readable
-    // message instead of crashing on .toUpperCase().
-    const currency = String(reference.transactionCurrencyCode).toUpperCase();
-    if (currency !== ctx.currency) {
-        throw new Error(`VGS credential currency mismatch: ${currency} vs ${ctx.currency}`);
-    }
-}
-function validateCliCredential(value) {
-    if (typeof value.tokenId !== 'string' || !value.tokenId.trim()) {
-        throw new Error('CLI agent credential requires tokenId');
-    }
-    // Deliberately no assuranceData requirement: the artifact's enrollment-time
-    // assurance is identity/enrollment material and is never read here (#5709).
-}
-/**
- * Refuse to mint an intent unless the assurance is fresh and its declared
- * scope matches the checkout target exactly. `now` is injectable so the
- * freshness rules are testable with a pinned clock (same pattern as
- * validateCredential).
- */
-export function validatePurchaseAssurance(value, target, now = new Date()) {
-    const remedy = 'run a fresh device-binding ceremony scoped to this exact merchant, amount, and ' +
-        'currency, and pass its output via --purchase-assurance-file (#5709)';
-    if (value == null || typeof value !== 'object') {
-        throw new Error(`purchase assurance is missing — ${remedy}`);
-    }
-    if (value.assuranceData == null) {
-        throw new Error(`purchase assurance requires assuranceData — ${remedy}`);
-    }
-    const mintedAtMs = typeof value.mintedAt === 'string' ? Date.parse(value.mintedAt) : NaN;
-    if (!Number.isFinite(mintedAtMs)) {
-        throw new Error(`purchase assurance requires an ISO 8601 mintedAt — ${remedy}`);
-    }
-    const age = now.getTime() - mintedAtMs;
-    if (age < -PURCHASE_ASSURANCE_MAX_SKEW_MS) {
-        throw new Error(`purchase assurance mintedAt is in the future — ${remedy}`);
-    }
-    if (age > PURCHASE_ASSURANCE_MAX_AGE_MS) {
-        throw new Error(`purchase assurance is stale (minted ${value.mintedAt}, limit ` +
-            `${PURCHASE_ASSURANCE_MAX_AGE_MS / 60000} minutes) — ${remedy}`);
-    }
-    let targetHost;
-    try {
-        targetHost = new URL(target.merchantUrl).hostname;
-    }
-    catch {
-        throw new Error('VGS checkout reference merchant URL is invalid');
-    }
-    if (value.merchantHost !== targetHost) {
-        throw new Error(`purchase assurance merchant mismatch: ${value.merchantHost} vs ${targetHost} — ${remedy}`);
-    }
-    const assuranceMinor = decimalToMinor(value.transactionAmount);
-    const targetMinor = decimalToMinor(target.transactionAmount);
-    if (assuranceMinor === null || assuranceMinor !== targetMinor) {
-        throw new Error(`purchase assurance amount mismatch: ${value.transactionAmount} vs ` +
-            `${target.transactionAmount} — ${remedy}`);
-    }
-    if (typeof value.transactionCurrencyCode !== 'string' ||
-        value.transactionCurrencyCode.toUpperCase() !==
-            String(target.transactionCurrencyCode).toUpperCase()) {
-        throw new Error(`purchase assurance currency mismatch: ${value.transactionCurrencyCode} vs ` +
-            `${target.transactionCurrencyCode} — ${remedy}`);
-    }
-}
-// `now` is injectable so expiry rules are testable with a pinned clock.
-export function validateCredential(value, now = new Date()) {
-    if (!/^\d{12,19}$/.test(value.networkToken)) {
-        throw new Error('VGS credential network token must contain 12-19 digits');
-    }
-    if (!/^\d{3,4}$/.test(value.cryptogramValue)) {
-        throw new Error('VGS credential short DAVV must contain 3-4 digits');
-    }
-    if (typeof value.cryptogramType !== 'string' || value.cryptogramType.toUpperCase() !== 'DAVV') {
-        throw new Error(`VGS credential type ${value.cryptogramType || '<missing>'} is not DAVV`);
-    }
-    if (!Number.isInteger(value.expMonth) || value.expMonth < 1 || value.expMonth > 12) {
-        throw new Error('VGS credential expiration month is invalid');
-    }
-    if (!Number.isInteger(value.expYear) ||
-        value.expYear < now.getFullYear() ||
-        (value.expYear === now.getFullYear() && value.expMonth < now.getMonth() + 1)) {
-        throw new Error('VGS credential is expired');
-    }
-    if (value.cryptogramExpiresAt !== undefined) {
-        const expiresAtMs = Date.parse(value.cryptogramExpiresAt);
-        if (!Number.isFinite(expiresAtMs))
-            throw new Error('VGS credential expiry is invalid');
-        if (expiresAtMs - now.getTime() < 60_000) {
-            throw new Error('VGS credential has less than 60 seconds of validity remaining');
-        }
-    }
-}
-/**
- * Mints the full DPAN + short DAVV only after the executor revalidates the
- * reviewed merchant, amount, and currency. The payment credential remains in
- * memory, is never returned to the caller, and can be requested only once.
- */
-export class VgsLiveInstrument {
-    reference;
-    cardholderName;
-    fetchCredential;
-    kind = 'agentic-token';
-    used = false;
-    minted = null;
-    constructor(reference, cardholderName, fetchCredential) {
-        this.reference = reference;
-        this.cardholderName = cardholderName;
-        this.fetchCredential = fetchCredential;
-    }
-    /**
-     * Non-null once VGS has actually issued a credential (the intent is consumed
-     * from that moment, even if local validation later rejects the credential) —
-     * exactly the population a VIC confirmation can be owed for.
-     */
-    confirmationTarget() {
-        return this.minted;
-    }
-    async getCredential(ctx) {
-        if (this.used)
-            throw new Error('VGS live credential instrument is single-use');
-        this.used = true;
-        validateTarget(this.reference, ctx);
-        if (!this.reference.tokenId || !this.reference.intentId) {
-            throw new Error('VGS checkout reference requires tokenId and intentId');
-        }
-        if (!this.cardholderName.trim())
-            throw new Error('cardholder name is required');
-        const { tokenId, intentId, ...transaction } = this.reference;
-        const value = await this.fetchCredential({ tokenId, intentId, transaction });
-        this.minted = { tokenId, intentId };
-        try {
-            validateCredential(value);
-        }
-        catch (err) {
-            // VGS already issued a cryptogram for this intent even though we refuse
-            // to fill it; "correct inputs and retry" would silently reuse a consumed
-            // intent, so steer the operator to a fresh one.
-            throw new Error(`${err.message} — a credential was issued by VGS but rejected locally; obtain a fresh intent before retrying`);
-        }
-        return {
-            pan: value.networkToken,
-            expMonth: value.expMonth,
-            expYear: value.expYear,
-            cvc: value.cryptogramValue,
-            cardholderName: this.cardholderName.trim(),
-            ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
-        };
-    }
-}
-/**
- * Consumes #5614's claimed CLI enrollment artifact (for the tokenId) plus a
- * FRESH purchase-scoped assurance, and creates a fresh, transaction-scoped VIC
- * intent + credential after checkout approval. This is the production-shaped
- * bridge; unlike VgsLiveInstrument it never needs a pre-created intent ID.
- *
- * The enrollment artifact's stored assuranceData is deliberately never sent:
- * replaying it makes intent creation succeed (HTTP 201) while the cryptogram
- * deterministically never completes — the #5709 dead end. Purchase
- * authorization is the fresh, merchant+amount+currency-scoped assurance,
- * validated against the checkout target BEFORE any intent is minted so a
- * doomed intent is never created.
- */
-export class VgsAssuranceInstrument {
-    enrollment;
-    purchase;
-    target;
-    cardholderName;
-    mintCredential;
-    kind = 'agentic-token';
-    used = false;
-    minted = null;
-    constructor(enrollment, purchase, target, cardholderName, mintCredential) {
-        this.enrollment = enrollment;
-        this.purchase = purchase;
-        this.target = target;
-        this.cardholderName = cardholderName;
-        this.mintCredential = mintCredential;
-    }
-    /** See VgsLiveInstrument.confirmationTarget — same contract. */
-    confirmationTarget() {
-        return this.minted;
-    }
-    async getCredential(ctx) {
-        if (this.used)
-            throw new Error('VGS assurance instrument is single-use');
-        this.used = true;
-        validateCliCredential(this.enrollment);
-        validateTarget(this.target, ctx);
-        validatePurchaseAssurance(this.purchase, this.target);
-        if (!this.cardholderName.trim())
-            throw new Error('cardholder name is required');
-        const { payment: value, intentId } = await this.mintCredential({
-            tokenId: this.enrollment.tokenId,
-            assuranceData: this.purchase.assuranceData,
-            transaction: this.target,
-        });
-        this.minted = { tokenId: this.enrollment.tokenId, intentId };
-        validateCredential(value);
-        return {
-            pan: value.networkToken,
-            expMonth: value.expMonth,
-            expYear: value.expYear,
-            cvc: value.cryptogramValue,
-            cardholderName: this.cardholderName.trim(),
-            ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
-        };
-    }
-}

package/dist/checkout-engine/vic-confirmation.d.ts

@@ -1,34 +0,0 @@
-import type { CheckoutOutcome } from './executor.js';
-import type { VicConfirmationTarget } from './vgs-live-instrument.js';
-export type VicTransactionStatus = 'APPROVED' | 'DECLINED';
-export type PostVicConfirmation = (input: {
-    tokenId: string;
-    intentId: string;
-    transactionStatus: VicTransactionStatus;
-    transactionType: 'PURCHASE';
-    transactionTimestamp: string;
-    transaction: {
-        transactionAmount: string;
-        transactionCurrencyCode: string;
-    };
-}) => Promise<unknown>;
-export type VicConfirmationReport = {
-    posted: true;
-    transactionStatus: VicTransactionStatus;
-} | {
-    posted: false;
-    reason: string;
-};
-/** Definitive merchant answers map to a status; everything else maps to none. */
-export declare function outcomeToTransactionStatus(outcome: CheckoutOutcome): VicTransactionStatus | null;
-export declare function reportVicOutcome(input: {
-    target: VicConfirmationTarget | null;
-    outcome: CheckoutOutcome;
-    transaction: {
-        transactionAmount: string;
-        transactionCurrencyCode: string;
-    };
-    post: PostVicConfirmation;
-    /** Injectable for tests; defaults to now. */
-    timestamp?: Date;
-}): Promise<VicConfirmationReport>;

package/dist/checkout-engine/vic-confirmation.js

@@ -1,39 +0,0 @@
-/** Definitive merchant answers map to a status; everything else maps to none. */
-export function outcomeToTransactionStatus(outcome) {
-    if (outcome === 'confirmed')
-        return 'APPROVED';
-    if (outcome === 'declined')
-        return 'DECLINED';
-    return null;
-}
-export async function reportVicOutcome(input) {
-    const transactionStatus = outcomeToTransactionStatus(input.outcome);
-    if (!transactionStatus) {
-        return {
-            posted: false,
-            reason: `outcome '${input.outcome}' is not a definitive merchant answer — ` +
-                'resolve it with the merchant, then post the confirmation manually',
-        };
-    }
-    if (!input.target) {
-        return { posted: false, reason: 'no VIC credential was minted in this run' };
-    }
-    try {
-        await input.post({
-            tokenId: input.target.tokenId,
-            intentId: input.target.intentId,
-            transactionStatus,
-            transactionType: 'PURCHASE',
-            transactionTimestamp: (input.timestamp ?? new Date()).toISOString(),
-            transaction: input.transaction,
-        });
-        return { posted: true, transactionStatus };
-    }
-    catch (err) {
-        return {
-            posted: false,
-            reason: `confirmation POST failed: ${err.message} — the merchant outcome stands; ` +
-                'retry the confirmation for this intent out-of-band',
-        };
-    }
-}

package/dist/skills/pair-visa-agent/RUNTIMES.md

@@ -1,79 +0,0 @@
-# Running the Visa pairing skill in OpenClaw **and** Hermes
-
-`@visa/visa-cli-openclaw` is packaged for OpenClaw, but the v4 **pairing** capability
-(`skills/pair-visa-agent/`) is deliberately runtime-agnostic: one skill works in OpenClaw,
-[Hermes](https://github.com/NousResearch/hermes-agent), or any runtime that can run the
-`visa` CLI or mount its MCP server. This doc is the map of how the two runtimes differ and
-why a single skill suffices.
-
-## The blunt fact: plugins are NOT portable
-
-| Axis            | OpenClaw                                                  | Hermes (NousResearch)                                                                                                                     |
-| --------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Language        | **JavaScript/TypeScript**                                 | **Python**                                                                                                                                |
-| Plugin manifest | `openclaw.plugin.json` + `definePluginEntry` (`index.ts`) | `~/.hermes/plugins/<name>/plugin.yaml` + `__init__.py`, `ctx.register_tool(...)`                                                          |
-| Config file     | `~/.openclaw/openclaw.json`                               | `~/.hermes/config.yaml`                                                                                                                   |
-| Skills          | markdown `SKILL.md` (+ optional UV scripts)               | markdown `~/.hermes/skills/<name>/` (agent-authored + curated Skills Hub)                                                                 |
-| MCP             | `openclaw.json` → `mcp.servers.*`                         | `config.yaml` → `mcp_servers.*`                                                                                                           |
-| Persona         | `SOUL.md`                                                 | `SOUL.md`                                                                                                                                 |
-| Migration       | —                                                         | `hermes claw migrate` (v0.3.0+): imports SOUL, memory, **skills → `~/.hermes/skills/openclaw-imports/`**, allowlists, and **MCP servers** |
-
-You cannot ship one plugin binary for both — the OpenClaw JS `pair_agent_*` tools in this
-package do not load in Hermes. **Do not try.**
-
-## What IS portable: markdown skills + MCP
-
-Both runtimes (a) read markdown skills natively and (b) mount MCP servers via an
-equivalent config block (`mcp.servers.*` ↔ `mcp_servers.*`, same `command`/`args`/`env`,
-same tool include/exclude). So the cross-runtime bridge is:
-
-1. **The `visa` CLI** — `visa agent enroll|enroll-claim --format json` (piped, load-bearing
-   exit codes). Any runtime that can execute a command can pair.
-2. **The `visa` MCP server** — the bundled `dist/mcp-server/index.js` entrypoint (there is
-   **no `visa mcp` subcommand**; `visa-cli install <client>` registers it, or configure it
-   by hand). Mount it identically in either runtime:
-
-   **OpenClaw** (`~/.openclaw/openclaw.json`):
-
-   ```json
-   {
-     "mcp": {
-       "servers": {
-         "visa-cli": {
-           "command": "node",
-           "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
-         }
-       }
-     }
-   }
-   ```
-
-   **Hermes** (`~/.hermes/config.yaml`):
-
-   ```yaml
-   mcp_servers:
-     visa-cli:
-       command: node
-       args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
-   ```
-
-3. **One `pair-visa-agent/SKILL.md`** — runtime-agnostic. It tells the agent to use
-   whichever pairing surface is present (`pair_agent_*` OpenClaw tools → `enroll_agent`
-   MCP tool → raw `visa agent …` CLI), all wrapping the same on-device hand-off.
-
-## So: how each runtime gets the capability
-
-| Runtime           | How it pairs                                                                                                                                                                                                                                 |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **OpenClaw**      | Install this package → the JS `pair_agent_start`/`pair_agent_poll` tools + the skill. (Or just the `visa` MCP server + the skill, no plugin.)                                                                                                |
-| **Hermes**        | Mount the `visa` MCP server in `config.yaml` (→ `enroll_agent`) and drop `pair-visa-agent/SKILL.md` into `~/.hermes/skills/`. `hermes claw migrate` will also import the skill from an existing OpenClaw install. No Python plugin required. |
-| **Anything else** | `visa` on PATH + the skill. The skill's raw-CLI path is the universal fallback.                                                                                                                                                              |
-
-## Optional: a symmetric Hermes plugin
-
-Not required — Hermes users get the full capability via the MCP server + skill above. If
-you want the _same named tools_ (`pair_agent_start`/`pair_agent_poll`) in Hermes, a thin
-`~/.hermes/plugins/visa-cli/` Python plugin (`plugin.yaml` + `__init__.py`) that shells out
-to `visa agent enroll|enroll-claim --format json` and registers the tools via
-`ctx.register_tool(...)` would mirror the OpenClaw plugin. Tracked as a fast-follow; the
-CLI + MCP + skill already make pairing "just work" in Hermes.