@descix/cli 1.0.8 → 1.0.10

package/agent-assets/instructions/onboarding-flow.md

@@ -294,6 +294,12 @@ User is trying to configure an app they don't own. Suggest purchase.
 ### "Folder already configured"
 Check if configuration matches intended app. Offer to update or skip.
 
+### Powch sign-in under `descix serve` fails ("User cancelled", or "WebAuthn is not supported on sites with TLS certificate errors")
+The gateway's dev certificate is not trusted. Run `descix dev-certs check`. If it is not trusted,
+give the user exactly `descix dev-certs trust` to run (macOS password prompt), tell them to quit
+and reopen Chrome, then run `descix dev-certs check` again. Details and Linux/Windows notes:
+`reference/local-dev.md` §3.3.
+
 ## Next Steps After Onboarding
 
 Once configured, guide user to:

package/agent-assets/reference/local-dev.md

@@ -187,11 +187,51 @@ a different case and FAILS LOUD naming the remedy, rather than quietly becoming
 
 The derived Shell rule is the important one: point the API at a cloud environment and the shell comes from that same origin, so one origin carries shell + app + `/apifront` with nothing else configured. A stale `env.platform.site` block does not hijack the root once the API is remote. Platform developers opt IN to a local shell by naming it (`--site-url https://localhost:5174` or `env.siteUrl`).
 
+### 3.3. The dev certificate and passkey sign-in
+
+The gateway's HTTPS uses one certificate: the pair named by `env.devCerts`
+(`descix config set-dev-certs`), else the SDK's shipped self-signed pair (SAN `localhost`,
+`127.0.0.1`, `::1`). The same pair serves every app dev server behind the gateway.
+
+**Chrome refuses WebAuthn on a tab whose certificate is untrusted, and it judges the whole tab.**
+The Powch sign-in iframe on `powch.descix.net` therefore fails inside an untrusted
+`https://localhost:<port>` tab, even though Powch's own origin is trusted.
+
+| Symptom | Meaning |
+|---|---|
+| Powch/ChatWidget log shows only `User cancelled` on sign-in | Powch's panel-close rejection; the real error is in the browser console |
+| Browser console: `NotAllowedError: WebAuthn is not supported on sites with TLS certificate errors` | the gateway certificate is not trusted (or has expired) |
+| `descix serve` banner: `Passkey sign-in will fail: <reason>. Run: descix dev-certs trust` | same, detected before the browser opens |
+| `descix doctor` row "Dev certificate" not passing | same |
+
+| Command | Who runs it | Effect |
+|---|---|---|
+| `descix dev-certs check [--json]` | the assisting agent | resolves the cert the gateway uses; exits 0 only when it is trusted; reports `unverifiable` with the reason on Linux and Windows |
+| `descix doctor` | the assisting agent | includes the same result as the "Dev certificate" check |
+| `descix dev-certs trust` | **the human** | macOS: trusts that cert in the login keychain (password prompt), re-checks, and says to quit and reopen Chrome |
+
+**Assisting-agent flow:**
+
+1. Run `descix doctor` (or `descix dev-certs check`).
+2. If the dev certificate is trusted, continue. Passkey failures then have another cause.
+3. If it is not trusted, hand the human exactly one command to run in their own terminal:
+   `descix dev-certs trust`. It needs their macOS login password, so the agent does not run it.
+4. When they report it succeeded, tell them to **quit Chrome completely and reopen it** (a running
+   Chrome keeps its old verdict), reload the `descix serve` URL, and sign in again.
+5. Run `descix dev-certs check` again and confirm exit 0 before calling sign-in fixed.
+
+**Linux and Windows:** the check reports `unverifiable`, and `descix dev-certs trust` is macOS-only.
+Trusting the cert is a manual step that has not been verified on DeSciX: import the gateway's
+`cert.pem` into the store Chrome reads (Linux: the NSS database,
+`certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n descix-localhost -i <cert.pem>`; Windows: the
+Current User "Trusted Root Certification Authorities" store), then restart the browser. Tell the
+human it is unverified.
+
 ## 4. Scenarios
 
 ### Scenario 1: App Dev (the common case)
 *   **User**: App developer. No platform checkout.
-*   **Setup**: `descix config set-env dev`, `descix app init`, `descix app set-site`, then `cd my-app && descix serve`.
+*   **Setup**: `descix config set-env dev`, `descix app init`, `descix app set-site`, `descix dev-certs check` (if not trusted, the human runs `descix dev-certs trust` once — §3.3), then `cd my-app && descix serve`.
 *   **Result**: one HTTPS origin. `/` → the cloud App Shell, `/apifront` → the cloud API, `/p/my-app` → your app, and the shell boots **standalone into your app** — its INITIAL VIEW is your app rather than the store, with the platform views still reachable from there.
 
 ### Scenario 2: Platform Dev ("Dogfooding")

package/agent-assets/reference/platform-api-consumer.md

@@ -91,11 +91,17 @@ ASSET NOT FOUND at gs://... Upload it first with `descix app media-upload`.
 Both come back as `MEDIA_ASSET_UNREADABLE`. The first means you referenced the wrong app's asset;
 the second means you have not uploaded yet. Upload into the app that will do the asking.
 
-**The upload verb hands you both forms, and both work.** `descix app media-upload` returns a
-`path` (relative to the app's assets prefix) and a `ref` (the `gs://` URI) for every file, plus a
-`public_url`; `--json` prints them for scripting. Either `path` or `ref` is a valid `asset_ref` —
-so if a rule in your head says the tool's own `ref` field is unusable, the rule is wrong, not the
-tool.
+**The upload verb hands you the relative `path`, and it is a valid `asset_ref` as-is.** `descix
+app media-upload` returns, per file, a `path` (relative to the app's assets prefix), a
+`public_url` (the app-host form, e.g. `https://{app}.descix.net/assets/<path>`), `gcs_path` and
+`content_type`; `--json` prints them for scripting. Pass `path` (or a `gs://` URI you construct
+yourself) as `asset_ref` — either form works, see below.
+
+**Who can upload, and how much.** Any app owner, community admin or platform admin may call
+`media-upload` for that app. Storage is capped **200 MB per app today** (pending credit-based
+metering for more) — the cap is enforced server-side by `get_asset_upload_token`, which refuses
+with its own message when a would-be upload exceeds it; the CLI never pre-checks quota locally,
+so trust that refusal over any local math.
 
 **The `gs://` form is accepted.** A `gs://` URI works as an `asset_ref` — it is parsed and
 scope-checked, and the handler then looks the object up by path. What is PROVEN is the form and

package/agent-assets/reference/workspace-config.md

@@ -33,7 +33,7 @@ is the schema and the verb that owns each key.
 | `env.environment` | `DEV`, `DEMO` or `PROD` | `descix config init --env dev\|demo\|prod` |
 | `env.apiUrl` | the API origin this workspace talks to | `descix config init --env …` (known envs) / `descix config set-env <name> --url <origin>` (custom) |
 | `env.gateway.port` | the port `descix serve` listens on | `descix config set-gateway-port <port>` |
-| `env.devCerts` | `dir`, or `cert` + `key` — the TLS pair for the gateway and every app behind it | `descix config set-dev-certs --dir\|--cert\|--key\|--clear` |
+| `env.devCerts` | `dir`, or `cert` + `key` — the TLS pair for the gateway and every app behind it; unset means the SDK's shipped pair. Passkey sign-in needs it trusted: `descix dev-certs check`, then the human runs `descix dev-certs trust` (see `reference/local-dev.md` §3.3) | `descix config set-dev-certs --dir\|--cert\|--key\|--clear` |
 | `env.powchUrl` | Powch's own origin (optional; Powch is cross-origin from the shell by design) | `descix config set-powch-url <url>` |
 | `env.siteUrl` | the App Shell origin the gateway proxies `/` to (optional; default is the API origin) | `descix config set-site-url <url>` |
 | `env.products[]` | one entry per app in this workspace, see below | `descix app init`, `app set-site`, `app set-port`, `app set-localpath`, `app unmap` |

package/bin/descix.js

@@ -40,35 +40,12 @@ import { kbVectorCell, kbCountSource } from '../lib/commands/kb-list-render.js';
 import * as corpusCommands from '../lib/commands/corpus.js';
 import * as modelConfigCommands from '../lib/commands/model-config.js';
 import { isHelpInvocation, getCommandSurface, applyVisibility } from '../lib/command-visibility.js';
+import { progress } from '../lib/output.js';
+import { runMediaUpload } from '../lib/commands/media-upload.js';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 
-
-/**
- * Emit human-facing PROGRESS for a command that can also emit JSON.
- *
- * When `--json` is set, stdout is a DATA CHANNEL: it must contain the JSON document and
- * nothing else, or every scripted consumer breaks. Progress then goes to stderr, where a
- * human piping stdout still sees it. Without `--json`, stdout is the human channel and
- * progress belongs there.
- *
- * ONE OWNER of that decision. Before this existed, each --json command re-decided it by
- * calling console.log directly, and both of them got it wrong: `mcp execute --json` prefixed
- * the document with "Executing <tool>..." and `app media-upload --json` prefixed it with a
- * header, a per-file listing and a per-file +/x line. Both exited 0, so a consumer saw a
- * success code and an unparseable stream. Measured 2026-08-21/22 (seat BEAST): two seats had
- * independently hand-rolled prefix-stripping workarounds (`tail -n +2`, `raw.find('[')`)
- * rather than reporting it.
- *
- * @param {Object} options - the command's parsed options (read for .json)
- * @param {...any} args - passed through to console.log / console.error
- */
-function progress(options, ...args) {
-  if (options && options.json) console.error(...args);
-  else console.log(...args);
-}
-
 /**
  * THE ONE OWNER of "a command threw, and the process must stop saying why".
  *
@@ -1196,15 +1173,12 @@ appCommand
 
 
 // descix app media-upload — upload media/asset files to an app's GCS assets prefix via the
-// API surface (WS-V1-PURGE Phase 1, item 2; media-via-API-surface PLATFORM half).
-// This is the canonical, filesystem-free way to get app media (podcast audio, cover art,
-// etc.) into the platform: request a short-lived signed PUT token from the API surface
-// (`get_asset_upload_token` over /apifront, user-session authed), upload each file straight
-// to GCS, and print the ASSET REFERENCES. An app microservice then fetches an uploaded asset
-// by reference over the Core broker via `get_app_asset` (no shared local filesystem needed).
+// API surface (WS-V1-PURGE Phase 1, item 2; media-via-API-surface PLATFORM half). Command body
+// lives in lib/commands/media-upload.js (runMediaUpload) — see that module for the full
+// contract (server-owned quota/path/permission checks, verbatim upload_headers ferrying).
 appCommand
   .command('media-upload')
-  .description('Upload media/asset files to an app\'s GCS assets prefix via the API surface (returns asset references)')
+  .description('Upload media/asset files to an app\'s GCS assets prefix (200 MB per app today; app owners, community admins and platform admins may upload — returns asset references)')
   .requiredOption('-a, --app <id>', 'App ID (community is resolved server-side from Products)')
   .requiredOption('-f, --file <path...>', 'One or more local file paths to upload')
   .option('--prefix <relPath>', 'Optional sub-path under the app assets/ prefix (e.g. "shows/myshow")', '')
@@ -1213,115 +1187,7 @@ appCommand
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-
-      const path = await import('path');
-      const mime = (await import('mime-types')).default;
-
-      const appId = options.app;
-      const localFiles = Array.isArray(options.file) ? options.file : [options.file];
-      const subPrefix = (options.prefix || '').replace(/^\/+|\/+$/g, '');
-
-      // Build the upload descriptor list: object path under assets/ = [subPrefix/]basename.
-      const fileDescriptors = [];
-      for (const localPath of localFiles) {
-        const abs = path.resolve(localPath);
-        let stat;
-        try {
-          stat = await fs.stat(abs);
-        } catch {
-          console.error(chalk.red(`\n❌ File not found: ${abs}\n`));
-          process.exit(1);
-        }
-        if (!stat.isFile()) {
-          console.error(chalk.red(`\n❌ Not a file: ${abs}\n`));
-          process.exit(1);
-        }
-        const base = path.basename(abs);
-        const objectPath = subPrefix ? `${subPrefix}/${base}` : base;
-        fileDescriptors.push({
-          path: objectPath,
-          content_type: mime.lookup(abs) || 'application/octet-stream',
-          size: stat.size,
-          _absolutePath: abs
-        });
-      }
-
-      console.log(chalk.cyan(`\n  Media Upload: ${appId} → GCS assets/\n`));
-      fileDescriptors.forEach(f => progress(options, chalk.gray(`  • ${f.path} (${(f.size / 1024).toFixed(1)}KB, ${f.content_type})`)));
-
-      // 1. Request a signed-PUT upload token over the API surface.
-      const tokenResponse = await apiClient.invoke('get_asset_upload_token', {
-        app_id: appId,
-        files: fileDescriptors.map(f => ({ path: f.path, content_type: f.content_type, size: f.size }))
-      });
-      const token = tokenResponse.message || tokenResponse;
-      const { signed_urls, objects } = token;
-
-      // 2. PUT each file directly to GCS using its signed URL.
-      progress(options, chalk.gray(`\n  Uploading ${fileDescriptors.length} file(s)...`));
-      const uploaded = [];
-      const errors = [];
-      for (const f of fileDescriptors) {
-        const signedUrl = signed_urls?.[f.path];
-        if (!signedUrl) {
-          errors.push(`No signed URL for: ${f.path}`);
-          progress(options, chalk.red(`  x ${f.path}`));
-          continue;
-        }
-        try {
-          const content = await fs.readFile(f._absolutePath);
-          const resp = await fetch(signedUrl, {
-            method: 'PUT',
-            headers: { 'Content-Type': f.content_type },
-            body: content
-          });
-          if (!resp.ok) {
-            errors.push(`Failed ${f.path}: ${resp.status} ${resp.statusText}`);
-            progress(options, chalk.red(`  x ${f.path}`));
-          } else {
-            const obj = (objects || []).find(o => o.path === f.path) || {};
-            // The asset REFERENCE an app handler / get_app_asset consumes: the gs:// URI.
-            const gcsRef = obj.gcs_path
-              ? `gs://${token.bucket}/${obj.gcs_path}`
-              : null;
-            uploaded.push({
-              path: f.path,
-              ref: gcsRef,
-              gcs_path: obj.gcs_path || null,
-              public_url: obj.public_url || null,
-              content_type: f.content_type,
-              size: f.size
-            });
-            progress(options, chalk.green(`  + ${f.path}`));
-          }
-        } catch (err) {
-          errors.push(`Error ${f.path}: ${err.message}`);
-          progress(options, chalk.red(`  x ${f.path}`));
-        }
-      }
-
-      if (errors.length > 0) {
-        progress(options, chalk.yellow(`\n  ${errors.length} error(s):`));
-        errors.forEach(e => progress(options, chalk.red(`  - ${e}`)));
-      }
-
-      if (uploaded.length === 0) {
-        console.error(chalk.red('\n❌ No files uploaded.\n'));
-        process.exit(1);
-      }
-
-      if (options.json) {
-        console.log('\n' + JSON.stringify({ app_id: appId, assets: uploaded }, null, 2) + '\n');
-      } else {
-        console.log(chalk.green(`\n  ✅ Uploaded ${uploaded.length} asset(s).\n`));
-        console.log(chalk.cyan('  Asset references (pass these to your app handler; the service fetches via get_app_asset):'));
-        uploaded.forEach(u => {
-          console.log(chalk.white(`    ${u.path}`));
-          console.log(chalk.gray(`      ref:        ${u.ref}`));
-          console.log(chalk.gray(`      public_url: ${u.public_url}`));
-        });
-        console.log();
-      }
+      await runMediaUpload(apiClient, options);
     } catch (error) {
       console.error(chalk.red(`\n❌ ${error.message}\n`));
       process.exit(1);
@@ -4627,6 +4493,37 @@ program
     }
   });
 
+// ============ Dev Certs Commands ============
+
+const devCertsCommand = program
+  .command('dev-certs')
+  .description('TLS dev-cert trust status for `descix serve` — passkey sign-in needs this cert trusted once per machine');
+
+devCertsCommand
+  .command('check')
+  .description('Check whether the dev-server cert is trusted for https://localhost (exit 0 only when trusted)')
+  .option('--json', 'Output raw JSON')
+  .action(async (options) => {
+    try {
+      const { runDevCertsCheck } = await import('../lib/commands/dev-certs.js');
+      await runDevCertsCheck(options);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+devCertsCommand
+  .command('trust')
+  .description('Trust the dev-server cert in the macOS keychain (prompts for your password)')
+  .action(async () => {
+    try {
+      const { runDevCertsTrust } = await import('../lib/commands/dev-certs.js');
+      await runDevCertsTrust();
+    } catch (error) {
+      fail(error);
+    }
+  });
+
 // ============ Quickstart Command ============
 
 program

package/bin/mcp-server.js

@@ -21,6 +21,8 @@ import { WorkspaceConfig } from '../lib/workspace-config.js';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { WalletFileManager } from '../lib/wallet-file.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
+import { checkDevCert } from '@descix/app-sdk/dev';
+import { resolveGatewayCertContext } from '../lib/dev-cert-resolver.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 // WS-MCP-SSOT-TIER2 (audit §5.B-1): the curated HTTP-valid core tools are the SINGLE SOURCE
@@ -322,6 +324,28 @@ try {
       }
     }
 
+    // Dev certificate — the ONE owner (checkDevCert, shared with `descix
+    // dev-certs`, `descix doctor` and the `descix serve` banner). An untrusted
+    // cert is invisible from inside a WebAuthn ceremony: Chrome judges the
+    // whole tab's TLS state and Powch only ever sees "User cancelled", so an
+    // agent assisting a stuck developer needs this named explicitly, not
+    // inferred from a login failure.
+    try {
+      const { certPath } = resolveGatewayCertContext(checkRoot);
+      const certResult = checkDevCert({ certPath });
+      report.dev_cert = { cert_path: certPath, ...certResult };
+      if (certResult.status !== 'trusted') {
+        report.warnings.push(
+          'Dev certificate not trusted: passkey sign-in under descix serve will fail ' +
+          '(Powch logs "User cancelled"; the console says "WebAuthn is not supported on sites ' +
+          'with TLS certificate errors"). Ask the user to run exactly: descix dev-certs trust ' +
+          '— then quit and reopen Chrome, and re-run descix dev-certs check.'
+        );
+      }
+    } catch (err) {
+      report.dev_cert = { status: 'unverifiable', detail: `Could not resolve dev cert: ${err.message}`, next: null };
+    }
+
     // Suggest cloud brain alignment when workspace is configured but alignment is missing
     if (!report.alignment && report.workspace?.configured) {
       report.suggestions = report.suggestions || [];

package/lib/commands/dev-certs.js

@@ -0,0 +1,93 @@
+/**
+ * dev-certs — report and (on trust) apply this machine's TLS trust status for
+ * the cert `descix serve` uses for its localhost HTTPS origin.
+ *
+ * Cert resolution is the ONE owner shared with `descix doctor` and the
+ * `descix serve` banner: lib/dev-cert-resolver.js -> @descix/app-sdk/dev's
+ * resolveDevCertOptions + resolveCertPaths. This file never re-derives which
+ * cert is "the" dev cert, and never mints or replaces one — the shipped
+ * SDK-tracked pair (descix-app-sdk/src/dev/certs/) is the only cert this
+ * command ever points at, same as every other consumer.
+ */
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+import { checkDevCert, trustCertCommand } from '@descix/app-sdk/dev';
+import { resolveGatewayCertContext } from '../dev-cert-resolver.js';
+
+/**
+ * `descix dev-certs check [--json]` — exits 0 only when the cert is trusted.
+ */
+export async function runDevCertsCheck(options = {}) {
+  const { certPath, port } = resolveGatewayCertContext(process.cwd());
+  const result = checkDevCert({ certPath });
+
+  if (options.json) {
+    console.log(JSON.stringify({ certPath, port, ...result }, null, 2));
+  } else {
+    console.log(chalk.cyan('\nDev certificate\n'));
+    console.log(`  Cert:   ${certPath}`);
+    console.log(`  Status: ${result.status === 'trusted' ? chalk.green(result.status) : chalk.red(result.status)}`);
+    console.log(`  Detail: ${result.detail}`);
+    if (result.next) {
+      console.log(`\n  Next:\n    ${String(result.next).replace(/\n/g, '\n    ')}`);
+    }
+    console.log('');
+  }
+
+  process.exitCode = result.status === 'trusted' ? 0 : 1;
+  return result;
+}
+
+/**
+ * `descix dev-certs trust` — the ONE final human command. Runs the exact
+ * trustCertCommand() string (macOS prompts for the keychain password), then
+ * re-checks and tells the human to reload Chrome. Refuses to run against a
+ * cert that is structurally broken (missing / no SAN / expired) or on a
+ * platform this cannot verify — those are not this command's job to paper
+ * over, and running `security add-trusted-cert` on a bad cert would silently
+ * "succeed" while passkeys still fail.
+ */
+export async function runDevCertsTrust() {
+  const { certPath, port } = resolveGatewayCertContext(process.cwd());
+  const before = checkDevCert({ certPath });
+
+  if (before.status === 'trusted') {
+    console.log(chalk.green(`\n${certPath} is already trusted.\n`));
+    return before;
+  }
+
+  if (before.status === 'unverifiable') {
+    // `security add-trusted-cert` is macOS-only — there is no automated trust
+    // step on this platform. Refuse loud rather than silently no-op, and hand
+    // the human the exact file so they can import it into their own OS/browser
+    // trust store by hand.
+    console.error(chalk.red(`\nCannot trust automatically on ${process.platform}: ${before.detail}`));
+    console.error(`\nImport this certificate into your OS/browser trust store manually:\n  ${certPath}\n`);
+    process.exitCode = 1;
+    return before;
+  }
+
+  if (before.status !== 'untrusted') {
+    console.error(chalk.red(`\nCannot trust this cert — status: ${before.status}`));
+    console.error(`  ${before.detail}`);
+    if (before.next) {
+      console.error(`\n  Next:\n    ${String(before.next).replace(/\n/g, '\n    ')}\n`);
+    }
+    process.exitCode = 1;
+    return before;
+  }
+
+  console.log(chalk.cyan('\nTrusting the dev certificate — macOS will prompt for your password.\n'));
+  execSync(trustCertCommand(certPath), { stdio: 'inherit' });
+
+  const after = checkDevCert({ certPath });
+  if (after.status === 'trusted') {
+    console.log(chalk.green('\nTrusted.'));
+    console.log(`Quit and reopen Chrome, then reload https://localhost:${port}/\n`);
+  } else {
+    console.error(chalk.red(`\nStill not trusted after running the trust command (${after.status}).`));
+    console.error(`  ${after.detail}\n`);
+    process.exitCode = 1;
+  }
+  return after;
+}

package/lib/commands/doctor.js

@@ -14,6 +14,8 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import { DeSciXApiClient } from '../api-client.js';
 import { isAuthenticated } from '../auth-guard.js';
+import { checkDevCert } from '@descix/app-sdk/dev';
+import { resolveGatewayCertContext } from '../dev-cert-resolver.js';
 
 const execAsync = promisify(exec);
 
@@ -223,6 +225,26 @@ export async function checkAdc() {
   }
 }
 
+/**
+ * Check the TLS cert `descix serve` would load for the cwd. An untrusted or
+ * structurally broken cert breaks passkey (WebAuthn) sign-in — the only
+ * DeSciX auth — so this is a real failure, not an admin-only advisory.
+ * Resolution mirrors the gateway exactly (dev-cert-resolver.js, the ONE
+ * owner shared with `descix dev-certs` and the `descix serve` banner).
+ */
+async function checkDevCertificate() {
+  const { certPath } = resolveGatewayCertContext(process.cwd());
+  const result = checkDevCert({ certPath });
+  if (result.status === 'trusted') {
+    return { ok: true, message: `${certPath} (trusted)` };
+  }
+  return {
+    ok: false,
+    message: `${result.status} — ${result.detail}`,
+    remediation: result.next || 'Run: descix dev-certs check',
+  };
+}
+
 /**
  * Run the doctor command
  */
@@ -282,7 +304,12 @@ export async function runDoctor(options = {}) {
     spinner.text = 'Checking ADC Credentials...';
     const adcRes = await checkAdc();
     results.push({ label: 'ADC Credentials', ...adcRes });
-    
+
+    // 7. Dev certificate (passkey sign-in under `descix serve`)
+    spinner.text = 'Checking dev certificate...';
+    const devCertRes = await checkDevCertificate();
+    results.push({ label: 'Dev certificate', ...devCertRes });
+
     spinner.stop();
     
     // Print Results
@@ -317,8 +344,9 @@ export async function runDoctor(options = {}) {
     // the pass stops.
     console.log(chalk.gray(
       'Checked: Node version, API origin resolution + reachability, session, local write\n' +
-      'permissions. [-] rows are admin-only dependencies and never fail this command. NOT\n' +
-      'checked: your app\'s own build, chain state, or any credential\'s permissions at the API.'
+      'permissions, dev-cert trust for `descix serve`. [-] rows are admin-only dependencies and\n' +
+      'never fail this command. NOT checked: your app\'s own build, chain state, or any\n' +
+      'credential\'s permissions at the API.'
     ));
     console.log();
 

package/lib/commands/media-upload.js

@@ -0,0 +1,176 @@
+/**
+ * `descix app media-upload` — upload media/asset files to an app's GCS assets prefix via the
+ * API surface (WS-V1-PURGE Phase 1, item 2; media-via-API-surface PLATFORM half; storage-cap
+ * ferrying added WS-MEDIA-QUOTA per CEO ruling 2026-09-16: "Yes you can build with a 200MB
+ * size limit for now until we get credit based metering for more storage.").
+ *
+ * This is the canonical, filesystem-free way to get app media (podcast audio, cover art, etc.)
+ * into the platform: request a short-lived signed PUT token from the API surface
+ * (`get_asset_upload_token` over /apifront, user-session authed), upload each file straight to
+ * GCS, and print the server's asset references. An app microservice then fetches an uploaded
+ * asset by reference over the Core broker via `get_app_asset` (no shared local filesystem
+ * needed). App owners, community admins and platform admins may upload — the server is the
+ * sole authority on that and on the app's storage quota (200 MB per app today; nothing here
+ * pre-validates either).
+ *
+ * SERVER IS THE SOLE AUTHORITY (super-DRY: never re-derive a server-owned fact client-side):
+ * - quota, path validity (no leading `/`, no backslash, no empty/`.`/`..` segment) and caller
+ *   permission are enforced ONLY by `get_asset_upload_token`; a refusal there throws with the
+ *   server's message verbatim (`DeSciXApiClient#invoke`) and this module does not catch it —
+ *   let it propagate so the caller prints exactly what the server said and exits non-zero.
+ * - `--prefix` is passed through UNCHANGED (no slash-stripping): stripping could silently mask
+ *   a server-side path refusal the server is best positioned to name.
+ * - Each file is PUT with the server's `upload_headers[path]` bag VERBATIM (precedent: `site
+ *   upload`'s `ferriedHeaders` — the server binds Content-Type and
+ *   `x-goog-content-length-range` into the v4 signed-URL signature, so a re-derived header
+ *   403s). Size is still read from `fs.stat`, since GCS itself rejects a body whose length
+ *   disagrees with the declared range.
+ * - `public_url` and `storage` are printed exactly as the server returned them — never
+ *   reconstructed from `bucket` + `gcs_path` (that WAS a client-side re-derivation of a server
+ *   fact; removed here rather than perpetuated).
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import chalk from 'chalk';
+import { progress } from '../output.js';
+
+/**
+ * Run `app media-upload`.
+ *
+ * @param {import('../api-client.js').DeSciXApiClient} apiClient
+ * @param {{app:string, file:string|string[], prefix?:string, json?:boolean}} options
+ * @returns {Promise<{app_id:string, assets:Array<object>, storage:object|null}>}
+ */
+export async function runMediaUpload(apiClient, options) {
+  const mime = (await import('mime-types')).default;
+
+  const appId = options.app;
+  const localFiles = Array.isArray(options.file) ? options.file : [options.file];
+  // No local normalization: a leading/trailing slash, empty segment, or `.`/`..` segment is a
+  // server-owned validity rule (get_asset_upload_token) — pass --prefix through untouched so a
+  // bad prefix surfaces as the server's own refusal, never a silently-corrected local guess.
+  const subPrefix = options.prefix || '';
+
+  // Build the upload descriptor list: object path under assets/ = [subPrefix/]basename.
+  const fileDescriptors = [];
+  for (const localPath of localFiles) {
+    const abs = path.resolve(localPath);
+    let stat;
+    try {
+      stat = await fs.stat(abs);
+    } catch {
+      throw new Error(`File not found: ${abs}`);
+    }
+    if (!stat.isFile()) {
+      throw new Error(`Not a file: ${abs}`);
+    }
+    const base = path.basename(abs);
+    const objectPath = subPrefix ? `${subPrefix}/${base}` : base;
+    fileDescriptors.push({
+      path: objectPath,
+      content_type: mime.lookup(abs) || 'application/octet-stream',
+      size: stat.size,
+      _absolutePath: abs
+    });
+  }
+
+  progress(options, chalk.cyan(`\n  Media Upload: ${appId} → GCS assets/\n`));
+  fileDescriptors.forEach(f => progress(options, chalk.gray(`  • ${f.path} (${(f.size / 1024).toFixed(1)}KB, ${f.content_type})`)));
+
+  // 1. Request a signed-PUT upload token over the API surface. The server owns quota, path
+  // validity and caller permission — a refusal here throws with the server's message verbatim
+  // and this function does not catch it.
+  const tokenResponse = await apiClient.invoke('get_asset_upload_token', {
+    app_id: appId,
+    files: fileDescriptors.map(f => ({ path: f.path, content_type: f.content_type, size: f.size }))
+  });
+  const token = tokenResponse.message || tokenResponse;
+  const { signed_urls, upload_headers, objects, storage } = token;
+
+  // 2. PUT each file directly to GCS using its signed URL and the server's exact header bag.
+  progress(options, chalk.gray(`\n  Uploading ${fileDescriptors.length} file(s)...`));
+  const uploaded = [];
+  const errors = [];
+  for (const f of fileDescriptors) {
+    const signedUrl = signed_urls?.[f.path];
+    if (!signedUrl) {
+      errors.push(`No signed URL for: ${f.path}`);
+      progress(options, chalk.red(`  x ${f.path}`));
+      continue;
+    }
+    // Never re-derive Content-Type (or the length-range header) locally for the PUT — the
+    // server binds them into the v4 signature. A path the server did not ferry a header bag
+    // for is an error for that path, naming the server as the thing that is missing it.
+    const headers = upload_headers?.[f.path];
+    if (!headers) {
+      errors.push(
+        `No upload_headers for: ${f.path} (get_asset_upload_token response is missing the header ` +
+        `bag for this path)`
+      );
+      progress(options, chalk.red(`  x ${f.path}`));
+      continue;
+    }
+    try {
+      const content = await fs.readFile(f._absolutePath);
+      const resp = await fetch(signedUrl, {
+        method: 'PUT',
+        headers,
+        body: content
+      });
+      if (!resp.ok) {
+        errors.push(`Failed ${f.path}: ${resp.status} ${resp.statusText}`);
+        progress(options, chalk.red(`  x ${f.path}`));
+      } else {
+        const obj = (objects || []).find(o => o.path === f.path) || {};
+        uploaded.push({
+          path: f.path,
+          gcs_path: obj.gcs_path || null,
+          public_url: obj.public_url || null,
+          content_type: f.content_type,
+          size: f.size
+        });
+        progress(options, chalk.green(`  + ${f.path}`));
+      }
+    } catch (err) {
+      errors.push(`Error ${f.path}: ${err.message}`);
+      progress(options, chalk.red(`  x ${f.path}`));
+    }
+  }
+
+  if (errors.length > 0) {
+    progress(options, chalk.yellow(`\n  ${errors.length} error(s):`));
+    errors.forEach(e => progress(options, chalk.red(`  - ${e}`)));
+  }
+
+  if (uploaded.length === 0) {
+    throw new Error('No files uploaded.');
+  }
+  if (errors.length > 0) {
+    // FAIL LOUD on a partial upload: the files that went up are listed above, but a caller that
+    // reads only the exit status must not take a half-uploaded set as success.
+    throw new Error(`${errors.length} of ${fileDescriptors.length} file(s) failed to upload:\n  - ${errors.join('\n  - ')}`);
+  }
+
+  const result = { app_id: appId, assets: uploaded, storage: storage || null };
+
+  if (options.json) {
+    console.log('\n' + JSON.stringify(result, null, 2) + '\n');
+  } else {
+    console.log(chalk.green(`\n  ✅ Uploaded ${uploaded.length} asset(s).\n`));
+    console.log(chalk.cyan('  Asset references (pass the path to your app handler; the service fetches via get_app_asset):'));
+    uploaded.forEach(u => {
+      console.log(chalk.white(`    ${u.path}`));
+      console.log(chalk.gray(`      public_url: ${u.public_url}`));
+    });
+    if (result.storage) {
+      // projected_bytes is the app's total INCLUDING this upload; used_bytes is the total before it.
+      const usedMb = (result.storage.projected_bytes / (1024 * 1024)).toFixed(1);
+      const limitMb = (result.storage.limit_bytes / (1024 * 1024)).toFixed(1);
+      console.log(chalk.gray(`\n  Storage: ${usedMb} MB / ${limitMb} MB used`));
+    }
+    console.log();
+  }
+
+  return result;
+}

package/lib/dev-cert-resolver.js

@@ -0,0 +1,50 @@
+/**
+ * resolveGatewayCertContext — the CLI-side mirror of which cert `descix serve`
+ * will load for a given cwd. ONE owner within the CLI: `doctor.js` and
+ * `dev-certs.js` both call this instead of re-deriving workspace lookup +
+ * resolveDevCertOptions + resolveCertPaths by hand — the same two-derivations
+ * risk `getViteHttpsConfig.js` names for the gateway itself.
+ *
+ * Mirrors gateway.js exactly: resolveDevCertOptions(workspaceRoot, {}, config)
+ * then resolveCertPaths(certOpts) — both from @descix/app-sdk/dev, the actual
+ * owner of "which TLS cert a local dev server uses". This module only supplies
+ * the workspaceRoot/config a CLI command has to hand; it never re-derives the
+ * precedence itself.
+ */
+import {
+  findWorkspaceRoot,
+  readWorkspaceConfig,
+  resolveDevCertOptions,
+  resolveCertPaths,
+  resolveGatewayPort,
+} from '@descix/app-sdk/dev';
+
+/**
+ * @param {string} cwd
+ * @returns {{
+ *   certPath: string,
+ *   keyPath: string,
+ *   workspaceRoot: string|null,
+ *   config: Object|null,
+ *   port: number,
+ *   portSource: string,
+ * }}
+ */
+export function resolveGatewayCertContext(cwd) {
+  const workspaceRoot = findWorkspaceRoot(cwd);
+  let config = null;
+  if (workspaceRoot) {
+    try {
+      config = readWorkspaceConfig(workspaceRoot);
+    } catch {
+      // A malformed workspace is the workspace resolver's problem to report
+      // elsewhere; this resolver just falls back to "no workspace opinion",
+      // same as resolveDevCertOptions does for a missing/malformed file.
+      config = null;
+    }
+  }
+  const certOpts = resolveDevCertOptions(workspaceRoot || cwd, {}, config);
+  const { certPath, keyPath } = resolveCertPaths(certOpts);
+  const { port, portSource } = resolveGatewayPort(config || {}, {});
+  return { certPath, keyPath, workspaceRoot, config, port, portSource };
+}

package/lib/output.js

@@ -0,0 +1,31 @@
+/**
+ * CLI output — ONE OWNER of the "human progress vs. --json data channel" split.
+ *
+ * Relocated from bin/descix.js (WS-MEDIA-QUOTA) so lib/commands/* modules can share it
+ * without bin/ -> lib/ layering going backwards. This is a move, not a duplication: bin/descix.js
+ * imports `progress` from here instead of defining its own copy.
+ */
+
+/**
+ * Emit human-facing PROGRESS for a command that can also emit JSON.
+ *
+ * When `--json` is set, stdout is a DATA CHANNEL: it must contain the JSON document and
+ * nothing else, or every scripted consumer breaks. Progress then goes to stderr, where a
+ * human piping stdout still sees it. Without `--json`, stdout is the human channel and
+ * progress belongs there.
+ *
+ * ONE OWNER of that decision. Before this existed, each --json command re-decided it by
+ * calling console.log directly, and both of them got it wrong: `mcp execute --json` prefixed
+ * the document with "Executing <tool>..." and `app media-upload --json` prefixed it with a
+ * header, a per-file listing and a per-file +/x line. Both exited 0, so a consumer saw a
+ * success code and an unparseable stream. Measured 2026-08-21/22 (seat BEAST): two seats had
+ * independently hand-rolled prefix-stripping workarounds (`tail -n +2`, `raw.find('[')`)
+ * rather than reporting it.
+ *
+ * @param {Object} options - the command's parsed options (read for .json)
+ * @param {...any} args - passed through to console.log / console.error
+ */
+export function progress(options, ...args) {
+  if (options && options.json) console.error(...args);
+  else console.log(...args);
+}

package/lib/verb-invokes.generated.json

@@ -116,6 +116,8 @@
   "credits refund": [
     "refund_credits"
   ],
+  "dev-certs check": [],
+  "dev-certs trust": [],
   "doctor": [],
   "drive pull": [],
   "drive push": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
     "descix-mcp": "bin/mcp-server.js"
   },
   "scripts": {
-    "test": "node --test \"tests/*.test.js\"",
+    "test": "node --experimental-test-module-mocks --test \"tests/*.test.js\"",
     "pack": "npm pack",
     "check:doc-paths": "node scripts/check-doc-paths.js",
     "briefer": "node scripts/briefer/run.mjs"
@@ -30,7 +30,7 @@
   "author": "DeSciX",
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@descix/app-sdk": "^0.1.5",
+    "@descix/app-sdk": "^0.1.8",
     "@descix/sdk": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "axios": "^1.7.9",

package/templates/agent-claude.md

@@ -174,6 +174,16 @@ resolves `--port` > `env.gateway.port` > 5173 and is printed with its source, so
 never hardcode `:5173`. Set your framework's base path to `/p/<appId>` — the
 gateway does not rewrite paths.
 
+**Passkey sign-in needs a trusted dev certificate.** If Powch sign-in under
+`descix serve` fails with `User cancelled`, or the browser console says
+`WebAuthn is not supported on sites with TLS certificate errors`, the gateway's
+certificate is not trusted. Run `descix dev-certs check` (or `descix doctor`, row
+"Dev certificate"). If it is not trusted, do not try to trust it yourself: give
+the user exactly `descix dev-certs trust` to run (macOS asks for their password),
+tell them to quit and reopen Chrome, then run `descix dev-certs check` again. On
+Linux and Windows the check reports `unverifiable` and trusting is a manual,
+unverified step — see `.descix/sdk-assets/reference/local-dev.md` §3.3.
+
 ## Integrating Existing Content
 
 If the repo already has content (an HTML page, a React app, an SDK with docs),

package/templates/agent-cline.md

@@ -136,6 +136,16 @@ resolves `--port` > `env.gateway.port` > 5173 and is printed with its source, so
 never hardcode `:5173`. Set your framework's base path to `/p/<appId>` — the
 gateway does not rewrite paths.
 
+**Passkey sign-in needs a trusted dev certificate.** If Powch sign-in under
+`descix serve` fails with `User cancelled`, or the browser console says
+`WebAuthn is not supported on sites with TLS certificate errors`, the gateway's
+certificate is not trusted. Run `descix dev-certs check` (or `descix doctor`, row
+"Dev certificate"). If it is not trusted, do not try to trust it yourself: give
+the user exactly `descix dev-certs trust` to run (macOS asks for their password),
+tell them to quit and reopen Chrome, then run `descix dev-certs check` again. On
+Linux and Windows the check reports `unverifiable` and trusting is a manual,
+unverified step — see `.descix/sdk-assets/reference/local-dev.md` §3.3.
+
 ## MCP Tools
 
 - `descix_doctor` — Startup diagnostic (call first)

package/templates/agent-copilot.md

@@ -136,6 +136,16 @@ resolves `--port` > `env.gateway.port` > 5173 and is printed with its source, so
 never hardcode `:5173`. Set your framework's base path to `/p/<appId>` — the
 gateway does not rewrite paths.
 
+**Passkey sign-in needs a trusted dev certificate.** If Powch sign-in under
+`descix serve` fails with `User cancelled`, or the browser console says
+`WebAuthn is not supported on sites with TLS certificate errors`, the gateway's
+certificate is not trusted. Run `descix dev-certs check` (or `descix doctor`, row
+"Dev certificate"). If it is not trusted, do not try to trust it yourself: give
+the user exactly `descix dev-certs trust` to run (macOS asks for their password),
+tell them to quit and reopen Chrome, then run `descix dev-certs check` again. On
+Linux and Windows the check reports `unverifiable` and trusting is a manual,
+unverified step — see `.descix/sdk-assets/reference/local-dev.md` §3.3.
+
 ## MCP Tools
 
 - `descix_doctor` — Startup diagnostic (call first)

package/templates/agent-cursor.md

@@ -136,6 +136,16 @@ resolves `--port` > `env.gateway.port` > 5173 and is printed with its source, so
 never hardcode `:5173`. Set your framework's base path to `/p/<appId>` — the
 gateway does not rewrite paths.
 
+**Passkey sign-in needs a trusted dev certificate.** If Powch sign-in under
+`descix serve` fails with `User cancelled`, or the browser console says
+`WebAuthn is not supported on sites with TLS certificate errors`, the gateway's
+certificate is not trusted. Run `descix dev-certs check` (or `descix doctor`, row
+"Dev certificate"). If it is not trusted, do not try to trust it yourself: give
+the user exactly `descix dev-certs trust` to run (macOS asks for their password),
+tell them to quit and reopen Chrome, then run `descix dev-certs check` again. On
+Linux and Windows the check reports `unverifiable` and trusting is a manual,
+unverified step — see `.descix/sdk-assets/reference/local-dev.md` §3.3.
+
 ## MCP Tools
 
 - `descix_doctor` — Startup diagnostic (call first)