studio-engine 0.63.0 → 0.64.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fcb787be0caeb8c975281d334f56a0d0ce699dbd25851b59948de0e5c6a87a4
-  data.tar.gz: a0b21daec66caf0110d3fc6f33f311a678b4216bda5b7d033011d84465ec54d3
+  metadata.gz: 30f8faae31ecb02586f53952db4bc53e74020245ec5f8c5e65bd642fca083d01
+  data.tar.gz: 975577b6f1160fea036860d099182484bc7a71faffdd825fbe979f873de24cb7
 SHA512:
-  metadata.gz: 26fdea81fbf8edcb85f0e6121c9bfa8b15dc34cf2b9166ebdd3cf158e2c09636d6ea5401baf203f293f6c2b2a866a2ddecdeacdd326c85bb3df6fa058af16800
-  data.tar.gz: 2493f082d861b7a8dadf60963df93c09aac10da94b6f0a7064644600b7da5bbd0079d0b58d4d1d1dbda717881f63af9fc53a5fdb9eab0c0ad644c1e7eaf5fb0b
+  metadata.gz: d60165b7dd31a39d72a9856f623d17257c31625f626012e57830df0c54410b65a4b90199e54985dad86f027a1cedf7cba87b5d9d27538c4764c970c6a6130769
+  data.tar.gz: d1f2cb9b37b5b92bc84ee8eb7cbc05cafd4be8d39aeda239b2a28d49e2b75e4ab8cde4051ee987efb963720aa806525c7c9a54a6057f78008fd96e70b40d34bf

data/app/controllers/solana_sessions_controller.rb

@@ -22,6 +22,15 @@ class SolanaSessionsController < ApplicationController
     render json: { nonce: session[:solana_nonce] }
   end
 
+  # Where Phantom redirects back to after a mobile signIn. The page itself does
+  # the work — decrypt Phantom's reply with the keypair the deep link stashed in
+  # localStorage, rebuild the signed message, and POST it to #verify — so this
+  # action only renders it. It must stay UNAUTHENTICATED: the whole point is
+  # that nobody is signed in yet.
+  def phantom_callback
+    render :phantom_callback
+  end
+
   def verify
     pubkey_b58 = verify_solana_signature!(
       message:       params[:message],

data/app/views/solana_sessions/phantom_callback.html.erb

@@ -0,0 +1,343 @@
+<div class="flex flex-col items-center justify-center min-h-[60vh] px-4">
+  <div class="text-center">
+    <div id="phantom-spinner" class="inline-block w-10 h-10 border-4 border-primary border-t-transparent rounded-full animate-spin mb-4"></div>
+    <p id="phantom-status" class="text-secondary text-sm">Processing Phantom response...</p>
+    <p id="phantom-error" class="text-red-400 text-sm mt-2 hidden"></p>
+  </div>
+
+  <%# Visual debug log — NEVER rendered on a real production deploy. This sink printed
+      the dapp x25519 secret key (phantom_dl_secret) to the page and the console on every
+      mobile Phantom sign-in. Studio.wallet_debug_sink DEFAULTS TO OFF —
+      a sink that prints a signing key is opted into, not defaulted on. An app that
+      wants QA debugging back sets it to a predicate of its own (turf-monster:
+      -> { !AppFlags.live_production? }); Rails.env.production? will NOT do, because
+      a Heroku QA dyno runs RAILS_ENV=production. The script below
+      treats an absent sink as "debug off" and must stay null-safe: if this div is gone and
+      dbg() still touched logEl, the callback would throw and break sign-in outright. %>
+  <% if Studio.wallet_debug_sink? %>
+    <div id="phantom-log" class="mt-6 w-full max-w-lg text-left bg-surface-alt rounded-lg border border-subtle p-3 overflow-y-auto" style="max-height:50vh">
+      <p class="text-xs font-mono text-muted mb-2">Debug Log</p>
+    </div>
+  <% end %>
+</div>
+
+<script>
+(function() {
+  var logEl = document.getElementById('phantom-log');
+  // The sink is absent on a real production deploy (see the ERB guard above), and that
+  // absence IS the off switch — for the console too, not just the page.
+  var DEBUG_SINK = !!logEl;
+
+  function dbg(label, value) {
+    if (!DEBUG_SINK) { return; }
+    var line = document.createElement('p');
+    line.className = 'text-xs font-mono break-all mb-1';
+    if (label === 'ERROR' || label === 'CATCH') {
+      line.style.color = '#EF4444';
+    } else if (label === 'OK') {
+      line.style.color = '#4BAF50';
+    } else {
+      line.style.color = '#94a3b8';
+    }
+    var val = (value === undefined || value === null) ? '' : String(value);
+    line.textContent = label + (val ? ': ' + val : '');
+    logEl.appendChild(line);
+    logEl.scrollTop = logEl.scrollHeight;
+    console.log('[PhantomDL]', label, value);
+  }
+
+  function truncate(s, n) {
+    return s && s.length > n ? s.substring(0, n) + '...' : s;
+  }
+
+  dbg('Page loaded', new Date().toISOString());
+  dbg('URL', window.location.href);
+
+  // Self-contained Base58
+  var B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+  function b58encode(bytes) {
+    var digits = [0];
+    for (var i = 0; i < bytes.length; i++) {
+      var carry = bytes[i];
+      for (var j = 0; j < digits.length; j++) {
+        carry += digits[j] << 8;
+        digits[j] = carry % 58;
+        carry = (carry / 58) | 0;
+      }
+      while (carry) { digits.push(carry % 58); carry = (carry / 58) | 0; }
+    }
+    var str = '';
+    for (var i = 0; i < bytes.length && bytes[i] === 0; i++) str += '1';
+    for (var i = digits.length - 1; i >= 0; i--) str += B58[digits[i]];
+    return str;
+  }
+
+  function b58decode(str) {
+    var bytes = [];
+    for (var i = 0; i < str.length; i++) {
+      var idx = B58.indexOf(str[i]);
+      if (idx < 0) throw new Error('Invalid base58 character');
+      var carry = idx;
+      for (var j = 0; j < bytes.length; j++) {
+        carry += bytes[j] * 58;
+        bytes[j] = carry & 0xff;
+        carry >>= 8;
+      }
+      while (carry) { bytes.push(carry & 0xff); carry >>= 8; }
+    }
+    for (var i = 0; i < str.length && str[i] === '1'; i++) bytes.push(0);
+    return new Uint8Array(bytes.reverse());
+  }
+
+  var statusEl = document.getElementById('phantom-status');
+  var errorEl = document.getElementById('phantom-error');
+  var spinnerEl = document.getElementById('phantom-spinner');
+
+  function showError(msg) {
+    dbg('ERROR', msg);
+    spinnerEl.classList.add('hidden');
+    statusEl.classList.add('hidden');
+    errorEl.textContent = msg;
+    errorEl.classList.remove('hidden');
+    setTimeout(function() { window.location.href = '/signin'; }, 30000);
+  }
+
+  var ALL_KEYS = [
+    'phantom_dl_secret', 'phantom_dl_pubkey', 'phantom_dl_nonce', 'phantom_dl_nonce_at',
+    'phantom_dl_step', 'phantom_dl_link_mode', 'phantom_dl_cluster', 'phantom_dl_age_attested'
+  ];
+
+  // Keys whose VALUE must never be printed. ALL_KEYS above stays COMPLETE on purpose:
+  // cleanup() iterates it to REMOVE these from localStorage, so pruning the secret from
+  // it would leave the private key sitting on the device forever — a worse bug than the
+  // one this task fixes. Redact at the point of display instead.
+  var SECRET_KEYS = ['phantom_dl_secret'];
+
+  function cleanup() {
+    ALL_KEYS.forEach(function(k) { localStorage.removeItem(k); });
+  }
+
+  // Dump localStorage
+  dbg('--- localStorage ---');
+  ALL_KEYS.forEach(function(k) {
+    var v = localStorage.getItem(k);
+    var short = k.replace('phantom_dl_', '');
+    if (SECRET_KEYS.indexOf(k) !== -1) {
+      dbg('  ' + short, v ? '(present, ' + v.length + ' chars, redacted)' : '(empty)');
+    } else {
+      dbg('  ' + short, v ? truncate(v, 40) : '(empty)');
+    }
+  });
+
+  // Parse + dump URL params
+  var params = new URLSearchParams(window.location.search);
+  dbg('--- URL params ---');
+  params.forEach(function(val, key) {
+    dbg('  ' + key, truncate(val, 40));
+  });
+
+  // Check for Phantom error
+  if (params.get('errorCode')) {
+    dbg('ERROR', 'errorCode=' + params.get('errorCode'));
+    dbg('ERROR', 'errorMessage=' + params.get('errorMessage'));
+    cleanup();
+    showError('Phantom error: ' + (params.get('errorMessage') || 'Request rejected'));
+    return;
+  }
+
+  var step = localStorage.getItem('phantom_dl_step');
+  dbg('Step', step);
+
+  if (!step) {
+    showError('No pending Phantom request. Redirecting to login...');
+    return;
+  }
+
+  // Check nonce expiry
+  var nonceAt = parseInt(localStorage.getItem('phantom_dl_nonce_at') || '0');
+  var elapsed = Date.now() - nonceAt;
+  dbg('Nonce age', Math.round(elapsed / 1000) + 's');
+  if (elapsed > 270000) {
+    cleanup();
+    showError('Session expired. Please try again.');
+    return;
+  }
+
+  // Check nacl
+  dbg('nacl available', typeof nacl !== 'undefined');
+  if (typeof nacl === 'undefined') {
+    showError('TweetNaCl not loaded');
+    return;
+  }
+
+  // URL params from Phantom response
+  var phantomEncPubkeyB58 = params.get('phantom_encryption_public_key');
+  var dataParm = params.get('data');
+  var nonceParm = params.get('nonce');
+
+  dbg('Has phantom_encryption_public_key', !!phantomEncPubkeyB58);
+  dbg('Has data', !!dataParm);
+  dbg('Has nonce', !!nonceParm);
+
+  if (!phantomEncPubkeyB58 || !dataParm || !nonceParm) {
+    cleanup();
+    showError('Missing Phantom response parameters');
+    return;
+  }
+
+  try {
+    // Recover dapp secret key from localStorage
+    var dappSecretKey = b58decode(localStorage.getItem('phantom_dl_secret'));
+    dbg('Dapp secret key bytes', dappSecretKey.length);
+
+    // Compute shared secret (Diffie-Hellman)
+    var phantomPubBytes = b58decode(phantomEncPubkeyB58);
+    dbg('Phantom pubkey bytes', phantomPubBytes.length);
+    var sharedSecret = nacl.box.before(phantomPubBytes, dappSecretKey);
+    dbg('OK', 'Shared secret computed, ' + sharedSecret.length + 'B');
+
+    // Decrypt response
+    var data = b58decode(dataParm);
+    var nonce = b58decode(nonceParm);
+    dbg('Decrypt', 'data=' + data.length + 'B nonce=' + nonce.length + 'B');
+
+    var decrypted = nacl.box.open.after(data, nonce, sharedSecret);
+    if (!decrypted) throw new Error('Decryption failed — nacl.box.open.after returned null');
+
+    var responseText = new TextDecoder().decode(decrypted);
+    dbg('OK', 'Decrypted ' + responseText.length + ' chars');
+
+    var response = JSON.parse(responseText);
+
+    // Log ALL response fields for debugging
+    dbg('=== RESPONSE FIELDS ===');
+    var keys = Object.keys(response);
+    dbg('Keys', keys.join(', '));
+    keys.forEach(function(k) {
+      var v = response[k];
+      if (typeof v === 'string') {
+        dbg('  ' + k, truncate(v, 50));
+      } else if (typeof v === 'object' && v !== null) {
+        dbg('  ' + k, JSON.stringify(v).substring(0, 80));
+      } else {
+        dbg('  ' + k, String(v));
+      }
+    });
+
+    // Extract wallet address
+    var walletPubkey = response.address || response.public_key;
+    dbg('Wallet', walletPubkey);
+
+    if (!walletPubkey) {
+      throw new Error('No wallet address in response');
+    }
+
+    // Extract signature and signed message (SIWS response)
+    var signatureB58 = response.signature;
+    var signedMessageB58 = response.signed_message || response.signedMessage;
+    var outputB58 = response.output;
+
+    dbg('signature', truncate(signatureB58, 30));
+    dbg('signedMessage', truncate(signedMessageB58, 30));
+    dbg('output', truncate(outputB58, 30));
+
+    // Decode the signed message to UTF-8 text (server expects the raw message string)
+    var message = null;
+    if (signedMessageB58) {
+      var msgBytes = b58decode(signedMessageB58);
+      message = new TextDecoder().decode(msgBytes);
+      dbg('Message text', truncate(message, 60));
+    }
+
+    // If no signature in response, show debug info and stop
+    if (!signatureB58) {
+      dbg('ERROR', 'No signature field in response — signIn may not return SIWS data');
+      dbg('Full response', responseText.substring(0, 200));
+      showError('No signature in Phantom response. See debug log.');
+      return;
+    }
+
+    if (!message) {
+      // Try to reconstruct message from our stored data
+      var serverNonce = localStorage.getItem('phantom_dl_nonce');
+      var domain = window.location.host;
+      // OPSEC-005: include `User-ID: <id>` when we were linking — mirrors
+      // the statement we built in startPhantomDeepLink so the server's
+      // session-binding check passes.
+      var storedUserId = localStorage.getItem('phantom_dl_user_id');
+      var storedLinkMode = localStorage.getItem('phantom_dl_link_mode') === 'true';
+      var statementLine = <%= Studio.wallet_sign_in_statement.to_json.html_safe %>;
+      if (storedLinkMode && storedUserId) {
+        statementLine += '\nUser-ID: ' + storedUserId;
+      }
+      message = domain + ' wants you to sign in with your Solana account:\n' +
+        walletPubkey + '\n\n' + statementLine + '\n\nNonce: ' + serverNonce;
+      dbg('Reconstructed message', truncate(message, 60));
+    }
+
+    var linkMode = localStorage.getItem('phantom_dl_link_mode') === 'true';
+    var verifyUrl = linkMode ? '/account/link_solana' : '/auth/solana/verify';
+    var csrfToken = document.querySelector('meta[name="csrf-token"]');
+
+    dbg('Verify URL', verifyUrl);
+    dbg('CSRF token', !!csrfToken);
+    dbg('POSTing to verify...');
+    statusEl.textContent = 'Logging in...';
+
+    fetch(verifyUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': csrfToken ? csrfToken.content : ''
+      },
+      body: JSON.stringify({
+        message: message,
+        signature: signatureB58,
+        pubkey: walletPubkey,
+        // Legal-age attestation, stashed by the Connect Wallet picker before
+        // the deep-link round trip (undefined is dropped by JSON.stringify).
+        age_attestation: (!linkMode && localStorage.getItem('phantom_dl_age_attested') === '1') ? '1' : undefined,
+        // Hardcoded, and correctly so: this whole page exists to service the
+        // PHANTOM mobile deep link (phantom_dl_*), so the brand is a property of
+        // the route rather than something to detect. A user arriving here signed
+        // in the Phantom app.
+        wallet_provider: 'phantom'
+      })
+    })
+    .then(function(r) {
+      dbg('Verify status', r.status);
+      return r.json();
+    })
+    .then(function(result) {
+      dbg('Verify result', JSON.stringify(result));
+      if (result.success) {
+        cleanup();
+        // Guarded, matching studio/modals/_wallet_connect two files over. An app
+        // that does not define this hook would otherwise throw HERE — after a
+        // successful verify, with the session already set — so the user is
+        // signed in and the page dies before redirecting. The engine cannot
+        // require a hook it does not ship.
+        if (typeof window.handleSolanaVerifySuccess === 'function') window.handleSolanaVerifySuccess(result);
+        dbg('OK', 'Login success! Redirecting...');
+        window.location.href = result.redirect || '/';
+      } else {
+        cleanup();
+        dbg('ERROR', 'Verify failed: ' + (result.error || JSON.stringify(result)));
+        showError(result.error || 'Verification failed');
+      }
+    })
+    .catch(function(err) {
+      dbg('ERROR', 'Fetch error: ' + err.message);
+      cleanup();
+      showError('Verification failed: ' + err.message);
+    });
+
+  } catch (e) {
+    dbg('CATCH', e.message);
+    dbg('CATCH', e.stack || '(no stack)');
+    cleanup();
+    showError(e.message || 'Something went wrong');
+  }
+})();
+</script>

data/app/views/studio/modals/_wallet_connect.html.erb

@@ -141,16 +141,31 @@
          var n = ('' + name).toLowerCase();
          return ['phantom', 'solflare', 'backpack'].indexOf(n) !== -1 ? n : null;
        },
+       // Is there anywhere for a mobile Phantom row to GO? A consumer that does
+       // not render studio/solana/phantom_deeplink has no startPhantomDeepLink,
+       // and every branch below turns on this answer.
+       //
+       // WHY IT IS CHECKED AT ALL: without it, adopting this picker replaced an
+       // app's dead-end install row with a dead BUTTON — the install row
+       // suppressed, the deep-link row painted, and its tap a no-op. Found
+       // before the hub adopted, which had no mobile wallet path whatsoever.
+       // An absent capability must not default to the permissive branch.
+       get canDeepLink() {
+         return typeof startPhantomDeepLink === 'function';
+       },
        // A phone has no extension to install, and Phantom's own row on mobile
        // is the deep link below — so drop Phantom here rather than paint a
        // SECOND Phantom row pointing at a desktop download page the user
-       // cannot act on. Solflare and Backpack keep their install rows: there is
-       // no deep link for them, so the download page is still their only path.
+       // cannot act on. ONLY when a deep link can replace it: with no deep
+       // link the install row is the only Phantom path there is, dead end on
+       // iOS or not, and removing it leaves the user nothing. Solflare and
+       // Backpack keep their install rows either way — there is no deep link
+       // for them, so the download page is still their only path.
        get missingInstalls() {
          var self = this;
          return this.installs.filter(function(i) {
            if (self.hasWallet(i.name)) return false;
-           if (self.isMobile && i.name === 'Phantom') return false;
+           if (self.isMobile && self.canDeepLink && i.name === 'Phantom') return false;
            return true;
          });
        },
@@ -158,7 +173,7 @@
        // means the detected row above already offers a working connect, so a
        // deep link would only offer to leave Phantom to open Phantom.
        get showPhantomDeepLink() {
-         return this.isMobile && !this.hasWallet('Phantom');
+         return this.isMobile && !this.hasWallet('Phantom') && this.canDeepLink;
        },
        async pick(name) {
          if (this.connecting) return;

data/app/views/studio/modals/blocks/_close_x.html.erb

@@ -13,6 +13,24 @@
   modals/_wallet_deposit, _wallet_topup, _cdp_ramp, _onramp_hub, _buy_entry_token
   and three under modals/auth/ (_paypal_tokens, _usdc_funding, _tokens).
 
+  THE /admin/style SPECIMENS SHOW STRUCTURE, NOT CONTENT. If you are adopting
+  this primitive to replace existing markup, take every VALUE — here modal_store
+  and label — from the markup you are REPLACING, and use the specimen only to
+  learn which locals exist and how they compose. A specimen is a demo: the
+  engine is entitled to pick any plausible value for it, and those values are
+  not your app's. style/modals/_ds_wallet_topup passes modal_store "dsModals",
+  its own page-scoped host; a callsite that copies it closes a store the app
+  does not have, so the mark renders and does nothing.
+
+  The incident that earned this paragraph: an adopter built a new callsite from
+  style/modals/_ds_wallet_topup and carried its icon across. The specimen passes
+  U+1F39F ADMISSION TICKETS; the markup being replaced had always drawn U+1F3AB
+  TICKET. A different glyph in a different colour landed on the primary rail of
+  the web2 kill-switch face of Top Up Wallet — the single call to action shown to
+  the audience that cannot pay with USDC. Nothing raised, CI was 6/6 green, and
+  no assertion anywhere pinned the glyph. It was caught only by rendering the
+  modal before and after and diffing the markup.
+
   THE PARENT MUST BE POSITIONED. This is `absolute`, so it anchors to the nearest
   positioned ancestor — every callsite wraps its card in `class="relative"`. On an
   unpositioned parent the × climbs to whatever is positioned above it, which in a

data/app/views/studio/modals/blocks/_rail_row.html.erb

@@ -9,6 +9,22 @@
   why that is a named local rather than a class passthrough — a passthrough would
   have let the eleventh copy drift on day one, which is how ten happened.
 
+  THE /admin/style SPECIMENS SHOW STRUCTURE, NOT CONTENT. If you are adopting
+  this primitive to replace existing markup, take every VALUE — icon_label,
+  icon_bg, title, subtitle, badge, data hooks — from the markup you are
+  REPLACING, and use the specimen only to learn which locals exist and how
+  they compose. A specimen is a demo: the engine is entitled to pick any
+  plausible value for it, and those values are not your app's.
+
+  The incident that earned this paragraph: an adopter built a new callsite from
+  style/modals/_ds_wallet_topup and carried its icon across. The specimen passes
+  U+1F39F ADMISSION TICKETS; the markup being replaced had always drawn U+1F3AB
+  TICKET. A different glyph in a different colour landed on the primary rail of
+  the web2 kill-switch face of Top Up Wallet — the single call to action shown to
+  the audience that cannot pay with USDC. Nothing raised, CI was 6/6 green, and
+  no assertion anywhere pinned the glyph. It was caught only by rendering the
+  modal before and after and diffing the markup.
+
   THE EMPHASIS IS A RANKING, not decoration. A hub full of equally-weighted rails
   asks the person to compare payment processors, which is not a question they can
   answer. Exactly one rail should be :primary — the one the app wants taken —

data/app/views/studio/modals/blocks/_success_card.html.erb

@@ -236,10 +236,17 @@
              :style="{ animation: 'studio-modal-drain ' + _total + 's linear forwards' }"></div>
         <span class="relative z-10"><%= cta_label %></span>
       </button>
+    <%# btn-lg, matching the drain branches above and every sibling in this family
+        (_onchain_success, _cta_redirect). Without it these two rendered 36px
+        (.btn alone: py-2 + text-sm) while the drain branch rendered 48 — the
+        same card, two heights, decided by whether an auto-redirect happened to
+        be configured. 36px is also under the 44px mobile touch-target
+        guideline. Not 40px: that is the HAND-ROLLED drain button one branch up
+        (px-4 py-2.5 text-sm), a different element with a different sum. %>
     <% elsif local_assigns[:cta_href_key] %>
-      <a :href="<%= cta_href_key %>" class="btn btn-primary w-full"><%= cta_label %></a>
+      <a :href="<%= cta_href_key %>" class="btn btn-primary btn-lg w-full"><%= cta_label %></a>
     <% elsif local_assigns[:cta_event] %>
-      <button @click="$dispatch('<%= cta_event %>')" class="btn btn-primary w-full"><%= cta_label %></button>
+      <button @click="$dispatch('<%= cta_event %>')" class="btn btn-primary btn-lg w-full"><%= cta_label %></button>
     <% end %>
   <% end %>
 

data/app/views/studio/solana/_deeplink_assets.html.erb

@@ -0,0 +1,37 @@
+<%#
+  tweetnacl, for the Phantom mobile deep link. Both halves of that flow need
+  window.nacl: the deep link generates an x25519 keypair so Phantom can encrypt
+  its reply, and the callback opens that box with the stashed secret.
+
+  IDEMPOTENT ON PURPOSE. turf-monster already loads tweetnacl from its own
+  layout, so this must not load a second copy there; the guard means a consumer
+  that already supplies nacl keeps its own and one that does not (the hub, which
+  had no mobile wallet path at all) gets it here.
+
+  Pinned to an exact version rather than a range: this is signing-path crypto,
+  and a range lets a CDN swap it under a running app. The same reasoning is
+  written out beside turf-monster's web3.js pin.
+
+  Render before studio/solana/phantom_deeplink and in the callback view.
+%>
+<script>
+  // NOT document.write. Under turbo-rails a Drive visit re-executes body scripts
+  // at readyState === 'complete', where document.write implicitly calls
+  // document.open() and BLANKS THE PAGE — on exactly the consumer this guard
+  // exists for. Append a real element instead; it is also non-blocking.
+  (function () {
+    if (typeof window.nacl !== 'undefined') return;
+    if (document.querySelector('script[data-studio-nacl]')) return;
+    var s = document.createElement('script');
+    s.src = 'https://cdn.jsdelivr.net/npm/tweetnacl@1.0.3/nacl-fast.min.js';
+    // Derived with `openssl dgst -sha384 -binary | openssl base64 -A` against the
+    // fetched file, and cross-checked against the value turf-monster already pins
+    // for this exact URL. NEVER hand-write an SRI: a plausible-looking wrong one
+    // makes the browser refuse the script and nacl silently absent, which fails
+    // every mobile sign-in before any other code runs.
+    s.integrity = 'sha384-05+sicyRJQ56XpL4U9HJ8YbtSzFDvAg7apPKOGV6A0JsAJKFM68jp5oLnUjG5mEp';
+    s.crossOrigin = 'anonymous';
+    s.setAttribute('data-studio-nacl', '');
+    document.head.appendChild(s);
+  })();
+</script>

data/app/views/studio/solana/_phantom_deeplink.html.erb

@@ -0,0 +1,167 @@
+<%#
+  Phantom MOBILE deep link — the round trip a phone needs to sign in with a
+  wallet. On desktop Phantom is a browser extension the page can call directly;
+  on a phone it is a separate APP, so the page hands off to it and comes back.
+
+  PROMOTED from turf-monster (app/javascript/phantom_deeplink.js) so every
+  consumer gets it. The server half was already shared — the engine's
+  solana_sessions_controller owns nonce + verify and Solana::SessionAuth owns
+  verify_solana_signature! — only this mobile round trip was app-side.
+
+  Render it once, wherever the Connect-Wallet flow can be reached — an ERB
+  output tag rendering the partial path "studio/solana/phantom_deeplink".
+  (Described rather than quoted on purpose: an ERB comment ends at the first
+  close sequence, so spelling the tag out here would terminate this comment and
+  leak the rest of it as visible text into every consuming app. The engine's
+  erb_comment_leak_test enforces that, and it caught this very paragraph.)
+
+  It defines window.startPhantomDeepLink(linkMode, currentUserId). The engine's
+  wallet picker (studio/modals/_wallet_connect) gates its mobile Phantom row on
+  that function EXISTING, so a consumer that does not render this partial keeps
+  its install row instead of painting a button that does nothing.
+
+  THREE THINGS THAT MUST NOT BE MADE CONFIGURABLE — traced through
+  Solana::SessionAuth#verify_solana_signature! before this was generalised:
+
+    domain        the client builds it from window.location.host and the server
+                  checks it against request.host_with_port (OPSEC-018). An app
+                  override breaks sign-in.
+    User-ID line  OPSEC-005 does a SUBSTRING match on "User-ID: <id>". Do not
+                  reformat it and do not translate it.
+    the nonce     deleted server-side BEFORE verification; that is the replay
+                  protection for the login path.
+
+  The STATEMENT is the one part that varies, and it varies safely: the server
+  does NOT verify it — it is what the human reads inside Phantom. It derives
+  from Studio.app_name, which reproduces turf-monster's previous literal
+  ("Sign in to Turf Monster") BYTE FOR BYTE, so promoting this changed no
+  signed message. It MUST match the callback's copy exactly, because the
+  callback reconstructs the signed message to post for verification — both read
+  this same helper, which is why they cannot drift.
+
+  Requires tweetnacl (window.nacl); render "studio/solana/deeplink_assets"
+  first, or supply it yourself.
+%>
+<script>
+  (function () {
+    var STATEMENT = <%= Studio.wallet_sign_in_statement.to_json.html_safe %>;
+
+    // Base58, INLINE and self-contained. turf-monster took this from a separate
+    // app/javascript/base58.js module that assigned window.encodeBase58, so its
+    // deep link depended on a second global. Promoting only the deep link would
+    // have left encodeBase58 undefined in any consumer without that file — it
+    // throws on the first keypair encode, at the moment the user taps Connect.
+    // The callback view already carries its own codec for the same reason; this
+    // matches it, so the partial has exactly one dependency (nacl) and it is a
+    // guarded one.
+    // THE CONSTANT THE ENCODER READS. It was left behind when the function body
+    // was inlined: base58.js declares it at module scope, so it is unreachable
+    // from a classic script, and encodeBase58 referenced a free variable that
+    // resolved to nothing AT CALL TIME. Every mobile sign-in threw
+    // "B58_ALPHABET is not defined" on the first keypair encode.
+    //
+    // Invisible to eleven passing view tests and to a browser spec that checked
+    // `typeof startPhantomDeepLink` without ever CALLING it. A parse-time
+    // mutation cannot reach this class either — the program parses fine.
+    const B58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+    function encodeBase58(bytes) {
+      const digits = [0];
+      for (let i = 0; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+          carry += digits[j] << 8;
+          digits[j] = carry % 58;
+          carry = (carry / 58) | 0;
+        }
+        while (carry) { digits.push(carry % 58); carry = (carry / 58) | 0; }
+      }
+      let str = '';
+      for (let i = 0; i < bytes.length && bytes[i] === 0; i++) str += '1';
+      for (let i = digits.length - 1; i >= 0; i--) str += B58_ALPHABET[digits[i]];
+      return str;
+    }
+
+    // Phantom deep link protocol for mobile browsers
+    // Uses signIn deep link — ONE trip to Phantom (connect + sign combined)
+    // Flow: generate keypair → fetch nonce → build SIWS input → redirect to Phantom signIn
+
+    function startPhantomDeepLink(linkMode, currentUserId) {
+      // The consumer declares its cluster on <body data-solana-cluster="...">.
+  // turf-monster does; an app that does NOT silently signs against devnet while
+  // its wallet is on mainnet, which reads to the user as a rejected signature
+  // and to the log as nothing. Warn loudly rather than guess quietly — the
+  // default stays devnet so behaviour is unchanged for anyone already relying
+  // on it.
+  var cluster = document.body.dataset.solanaCluster;
+  if (!cluster) {
+    console.warn('[StudioSolana] no data-solana-cluster on <body>; defaulting to devnet. ' +
+                 'Set it on the body tag to sign against the cluster you mean.');
+    cluster = 'devnet';
+  }
+      var callbackUrl = window.location.origin + '/auth/phantom/callback';
+
+      // Generate x25519 keypair for decrypting Phantom's response
+      var dappKeyPair = nacl.box.keyPair();
+
+      // Fetch nonce from server, then redirect to Phantom signIn
+      fetch('/auth/solana/nonce')
+        .then(function(r) { return r.json(); })
+        .then(function(data) {
+          // OPSEC-005: when linking a wallet to a logged-in user, embed
+          // `User-ID: <id>` so the server can refuse signatures captured
+          // against a different session's nonce. Login (no currentUserId)
+          // skips the binding line.
+          var statement = STATEMENT;
+          if (linkMode && currentUserId) {
+            statement = statement + '\nUser-ID: ' + currentUserId;
+          }
+
+          // Build SIWS input (CAIP-122 / Sign In With Solana format)
+          // Note: chainId omitted — optional per spec, avoids mismatch warning
+          // when app is on devnet but user's wallet is on mainnet
+          var signInInput = {
+            domain: window.location.host,
+            statement: statement,
+            uri: window.location.origin,
+            version: '1',
+            nonce: data.nonce,
+            issuedAt: new Date().toISOString()
+          };
+
+          // Save state to localStorage (persists across redirect)
+          localStorage.setItem('phantom_dl_secret', encodeBase58(dappKeyPair.secretKey));
+          localStorage.setItem('phantom_dl_pubkey', encodeBase58(dappKeyPair.publicKey));
+          localStorage.setItem('phantom_dl_nonce', data.nonce);
+          localStorage.setItem('phantom_dl_nonce_at', Date.now().toString());
+          localStorage.setItem('phantom_dl_step', 'signIn');
+          localStorage.setItem('phantom_dl_link_mode', linkMode ? 'true' : 'false');
+          localStorage.setItem('phantom_dl_cluster', cluster);
+          if (currentUserId) {
+            localStorage.setItem('phantom_dl_user_id', String(currentUserId));
+          } else {
+            localStorage.removeItem('phantom_dl_user_id');
+          }
+
+          // Base58-encode the SIWS input JSON (NOT encrypted — per Phantom signIn protocol)
+          var payloadB58 = encodeBase58(new TextEncoder().encode(JSON.stringify(signInInput)));
+
+          // Build Phantom signIn deep link
+          var params = new URLSearchParams({
+            dapp_encryption_public_key: encodeBase58(dappKeyPair.publicKey),
+            cluster: cluster,
+            app_url: window.location.origin,
+            redirect_link: callbackUrl,
+            payload: payloadB58
+          });
+
+          window.location.href = 'https://phantom.app/ul/v1/signIn?' + params.toString();
+        })
+        .catch(function(err) {
+          alert('Failed to start Phantom connection: ' + err.message);
+        });
+    }
+
+    window.startPhantomDeepLink = startPhantomDeepLink;
+  })();
+</script>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.63.0"
+  VERSION = "0.64.0"
 end

data/lib/studio.rb

@@ -56,6 +56,46 @@ module Studio
   mattr_accessor :after_newsletter_change, default: ->(_user, subscribed:, first_join:) {}
   mattr_accessor :sso_logo,            default: nil
   mattr_accessor :wallet_address_method, default: nil
+
+  # The statement a wallet signs, and the line the human reads inside Phantom.
+  # Deliberately DERIVED rather than configured: "Sign in to Turf Monster" was
+  # turf-monster's literal before the mobile deep link was promoted, and
+  # app_name reproduces it byte for byte, so nothing that was already signed
+  # changed. Safe to vary because the server does NOT verify this text — see
+  # Solana::SessionAuth#verify_solana_signature!, which checks the nonce, the
+  # host, and the OPSEC-005 User-ID binding, and nothing else about the message.
+  # UNVERIFIED IS NOT UNCONSTRAINED. Solana::AuthVerifier reads the nonce with a
+  # FIRST-MATCH /Nonce: (\w+)/ and the statement is interpolated ABOVE the real
+  # nonce line, so a statement containing "Nonce: something" would be read as the
+  # nonce and fail every verify. Not an attack surface (this is app config, never
+  # user input) but a real constraint on what may be put here.
+  # Both the deep-link partial and the callback view read THIS, so they cannot
+  # drift; the callback rebuilds the signed message to post for verification, so
+  # a drift between them would fail every mobile sign-in.
+  mattr_accessor :wallet_sign_in_statement_builder,
+                 default: -> { "Sign in to #{Studio.app_name}" }
+
+  def self.wallet_sign_in_statement
+    wallet_sign_in_statement_builder.call
+  end
+
+  # The Phantom callback's on-page debug sink. DEFAULTS TO OFF, and the default
+  # is the point: that sink printed the dapp x25519 SECRET KEY to the page and
+  # the console on every mobile sign-in. A capability that leaks a signing key
+  # must be opted INTO, never defaulted on and switched off per environment.
+  #
+  # Rails.env.production? is the wrong predicate here and that is why this is a
+  # lambda rather than an env check: a Heroku QA dyno runs RAILS_ENV=production,
+  # so an env test would take QA's debugging away. turf-monster restores exactly
+  # what it had with:
+  #
+  #     config.wallet_debug_sink = -> { !AppFlags.live_production? }
+  #
+  # The callback treats an absent sink as "debug off" and stays null-safe, so
+  # turning this off can never break sign-in.
+  mattr_accessor :wallet_debug_sink, default: -> { false }
+
+  def self.wallet_debug_sink? = wallet_debug_sink.call
   mattr_accessor :theme_logos,         default: []
   mattr_accessor :sticky_table_headers, default: false
 
@@ -782,13 +822,18 @@ module Studio
              constraints: { token: %r{[^/]+} }
       end
 
-      # Solana / Phantom wallet sign-in (nonce challenge + signature verify).
-      # The browser posts to these literal paths from the shared Connect-Wallet
-      # flow; app-specific surfaces (mobile deep-link callback, account-linking,
-      # OAuth popup) stay in the consuming app's routes.
+      # Solana / Phantom wallet sign-in (nonce challenge + signature verify),
+      # plus the MOBILE deep-link callback Phantom redirects back to. The
+      # callback used to be listed here as app-specific and is not any more —
+      # it was promoted with the deep link itself, because the hub had no
+      # mobile wallet path at all and copying 400 lines of SIWS protocol per
+      # app is how the picker came to exist three times. Account-linking and
+      # the OAuth popup DO stay app-side.
       if Studio.draw_auth_routes && Studio.auth_method?(:wallet)
         get  "auth/solana/nonce",  to: "solana_sessions#nonce",  as: :solana_nonce
         post "auth/solana/verify", to: "solana_sessions#verify", as: :solana_verify
+        get  "auth/phantom/callback", to: "solana_sessions#phantom_callback",
+             as: :phantom_callback
       end
 
       # The shared profile page. ON by default — unlike /admin/emails and the

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.63.0
+  version: 0.64.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -401,6 +401,7 @@ files:
 - app/views/schema/index.html.erb
 - app/views/sessions/_sso_continue.html.erb
 - app/views/sessions/new.html.erb
+- app/views/solana_sessions/phantom_callback.html.erb
 - app/views/studio/_at_time_script.html.erb
 - app/views/studio/_birthday_assets.html.erb
 - app/views/studio/_board_assets.html.erb
@@ -498,6 +499,8 @@ files:
 - app/views/studio/profiles/_save_controls.html.erb
 - app/views/studio/profiles/edit.html.erb
 - app/views/studio/profiles/show.html.erb
+- app/views/studio/solana/_deeplink_assets.html.erb
+- app/views/studio/solana/_phantom_deeplink.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
 - app/views/style/_specimen.html.erb