spaps 0.7.8 → 0.8.0

package/README.md

@@ -295,6 +295,38 @@ That bridge does three things:
 - intercepts `/api/auth/user`, `/api/auth/login`, `/api/auth/logout`, `/api/entitlements`, and `/api/entitlements/check`
 - renders a tiny persona switcher so you can flip between `user`, `admin`, and `premium`
 
+Personas can also carry app-owned demo state in `.spaps/users.json`:
+
+```json
+{
+  "code": "pds-initiator",
+  "display_name": "PDS Initiator",
+  "profile": { "user_id": "00000000-0000-0000-0000-000000000001" },
+  "scenario": {
+    "pds": {
+      "dashboard": "work",
+      "role": "initiator"
+    }
+  }
+}
+```
+
+`scenario` is opaque to SPAPS. It is copied into `browser/<persona>.context.json`, persisted as `spaps.fixture.scenario`, and exposed by the bridge:
+
+```js
+const pdsScenario = window.__SPAPS_DEV_AUTH__.getScenario("pds");
+
+const unsubscribe = window.__SPAPS_DEV_AUTH__.onPersonaChange((event) => {
+  console.log(event.persona.code, event.scenario.pds);
+});
+
+window.addEventListener("spaps:persona-change", (event) => {
+  console.log(event.detail.persona.code);
+});
+```
+
+Use this for persona-specific dashboard stories, queues, and UI fixture hints. Keep product-specific data in the consuming app; SPAPS only owns the persona/auth/role/entitlement envelope.
+
 ## Middleware Example
 
 The main module exports admin and permission helpers for Express-style apps.

package/assets/local-runtime/Dockerfile

@@ -12,12 +12,13 @@ RUN apt-get update && \
         curl \
     && rm -rf /var/lib/apt/lists/*
 
-ARG SPAPS_SERVER_QUICKSTART_VERSION=0.5.0
+ARG SPAPS_SERVER_QUICKSTART_VERSION=0.5.1
 RUN pip install --no-cache-dir "spaps-server-quickstart==${SPAPS_SERVER_QUICKSTART_VERSION}"
 RUN python - <<'PY'
 from pathlib import Path
 
 from spaps_server_quickstart.domains.auth import schemas
+from spaps_server_quickstart.middleware import local_mode
 
 schema_path = Path(schemas.__file__)
 text = schema_path.read_text(encoding="utf-8")
@@ -26,6 +27,16 @@ text = text.replace(
     "    refresh_token: str | None = None\n",
 )
 schema_path.write_text(text, encoding="utf-8")
+
+local_mode_path = Path(local_mode.__file__)
+text = local_mode_path.read_text(encoding="utf-8")
+text = text.replace(
+    'default_factory=lambda: {"issue_reporting_required_capability": "view_products"}',
+    'default_factory=lambda: {"issue_reporting_required_capability": "view_products", "issue_reporting_input_modes": ["text", "voice"]}',
+)
+if '"issue_reporting_input_modes"' not in text:
+    raise RuntimeError("Failed to patch local-mode issue reporting input modes")
+local_mode_path.write_text(text, encoding="utf-8")
 PY
 
 COPY alembic.ini /app/alembic.ini

package/assets/local-runtime/alembic/versions/000000000024_app_links.py

@@ -0,0 +1,55 @@
+"""application-scoped short links
+
+Revision ID: 000000000024
+Revises: 000000000018
+Create Date: 2026-05-03
+
+Adds app_links, a reusable per-application short-link table for browser
+applications that need stable public URLs for compressed state.
+"""
+
+from alembic import op
+
+revision = "000000000024"
+down_revision = "000000000018"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE IF NOT EXISTS app_links (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            application_id UUID NOT NULL
+                REFERENCES applications(id) ON DELETE CASCADE,
+            owner_user_id UUID NOT NULL
+                REFERENCES users(id) ON DELETE CASCADE,
+            owner_username VARCHAR(64) NOT NULL,
+            slug VARCHAR(48) NOT NULL,
+            app_slug VARCHAR(64) NOT NULL,
+            resource_kind VARCHAR(64) NOT NULL,
+            title VARCHAR(160),
+            target_path TEXT NOT NULL,
+            metadata JSONB DEFAULT '{}'::jsonb,
+            click_count INTEGER NOT NULL DEFAULT 0,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            CONSTRAINT uq_app_links_application_owner_slug
+                UNIQUE (application_id, owner_username, slug)
+        );
+    """)
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_app_links_application_owner_created
+        ON app_links (application_id, owner_user_id, created_at DESC);
+    """)
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_app_links_public_lookup
+        ON app_links (application_id, owner_username, slug);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS ix_app_links_public_lookup;")
+    op.execute("DROP INDEX IF EXISTS ix_app_links_application_owner_created;")
+    op.execute("DROP TABLE IF EXISTS app_links;")
+

package/assets/local-runtime/alembic/versions/000000000025_x402_svm_fee_payer.py

@@ -0,0 +1,30 @@
+"""x402 SVM fee payer billing account ref
+
+Revision ID: 000000000025
+Revises: 000000000024
+Create Date: 2026-05-03
+
+Adds the trusted Solana fee-payer wallet reference required by exact SVM x402
+payment requirements.
+"""
+
+from alembic import op
+
+revision = "000000000025"
+down_revision = "000000000024"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        ALTER TABLE billing_accounts
+        ADD COLUMN IF NOT EXISTS x402_fee_payer_wallet_ref TEXT;
+    """)
+
+
+def downgrade() -> None:
+    op.execute("""
+        ALTER TABLE billing_accounts
+        DROP COLUMN IF EXISTS x402_fee_payer_wallet_ref;
+    """)

package/assets/local-runtime/docker-compose.yml

@@ -4,7 +4,7 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        SPAPS_SERVER_QUICKSTART_VERSION: ${SPAPS_SERVER_QUICKSTART_VERSION:-0.5.0}
+        SPAPS_SERVER_QUICKSTART_VERSION: ${SPAPS_SERVER_QUICKSTART_VERSION:-0.5.1}
     restart: unless-stopped
     ports:
       - "${SPAPS_LOCAL_PORT:-3301}:8000"

package/assets/local-runtime/manifest.json

@@ -1,5 +1,5 @@
 {
-  "spaps_server_quickstart_version": "0.5.0",
+  "spaps_server_quickstart_version": "0.5.1",
   "portable_runtime": {
     "default_local_mode": true,
     "default_auth_base_url": "http://localhost:5173",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.8",
+  "version": "0.8.0",
   "description": "Sweet Potato Authentication & Payment Service CLI - Docker Compose orchestrator for local Python/FastAPI SPAPS server with built-in admin middleware",
   "main": "src/index.js",
   "bin": {

package/src/fixture-kernel.js

@@ -17,6 +17,7 @@ const FIXTURE_KEYS = {
   profile: 'spaps.fixture.profile',
   roles: 'spaps.fixture.roles',
   entitlements: 'spaps.fixture.entitlements',
+  scenario: 'spaps.fixture.scenario',
   application: 'spaps.fixture.application',
   runtime: 'spaps.fixture.runtime',
   selector: 'spaps.fixture.selector',
@@ -1384,6 +1385,7 @@ function buildBridgeConfig(appConfig, users, rolesConfig, entitlementsConfig) {
       tokens: buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []),
       entitlement_keys: entitlementsConfig.grants?.[persona.code] || [],
       entitlements: buildEntitlementRecords(appConfig, persona, entitlementsConfig),
+      scenario: persona.scenario || {},
       browser: {
         local_storage: persona.browser?.local_storage || {},
       },
@@ -1407,8 +1409,14 @@ function buildDevAuthBridgeScript(config) {
   const PERSONA_LOCAL_STORAGE_KEYS = Array.from(new Set(
     CONFIG.personas.flatMap((persona) => Object.keys(persona.browser?.local_storage || {}))
   ));
+  const personaChangeListeners = [];
   const originalFetch = typeof window.fetch === 'function' ? window.fetch.bind(window) : null;
 
+  function clone(value) {
+    if (value === undefined || value === null) return value;
+    return JSON.parse(JSON.stringify(value));
+  }
+
   function toAbsoluteUrl(input) {
     if (input instanceof Request) return new URL(input.url, window.location.origin);
     return new URL(String(input), window.location.origin);
@@ -1427,6 +1435,63 @@ function buildDevAuthBridgeScript(config) {
     return getPersonaByCode(localStorage.getItem(ACTIVE_PERSONA_KEY)) || getPersonaByCode(getInitialPersonaCode()) || CONFIG.personas[0];
   }
 
+  function getScenario(namespace) {
+    const scenario = getCurrentPersona().scenario || {};
+    if (!namespace) return clone(scenario);
+    return Object.prototype.hasOwnProperty.call(scenario, namespace) ? clone(scenario[namespace]) : null;
+  }
+
+  function publicPersona(persona) {
+    if (!persona) return null;
+    return {
+      code: persona.code,
+      display_name: persona.display_name,
+      selector: clone(persona.selector || {}),
+      route_hint: persona.route_hint || null,
+      application: clone(persona.application || CONFIG.application),
+      user: clone(persona.user),
+      roles: clone(persona.user?.roles || []),
+      entitlements: clone(persona.entitlement_keys || []),
+      scenario: clone(persona.scenario || {})
+    };
+  }
+
+  function buildPersonaChangeDetail(previousPersona, persona) {
+    return {
+      persona: publicPersona(persona),
+      previous_persona: publicPersona(previousPersona),
+      user: clone(persona?.user || null),
+      scenario: clone(persona?.scenario || {})
+    };
+  }
+
+  function emitPersonaChange(previousPersona, persona) {
+    const detail = buildPersonaChangeDetail(previousPersona, persona);
+    personaChangeListeners.slice().forEach((listener) => {
+      try {
+        listener(detail);
+      } catch (error) {
+        console.error('[spaps-dev-auth] persona change listener failed', error);
+      }
+    });
+
+    if (typeof window.dispatchEvent === 'function' && typeof CustomEvent === 'function') {
+      window.dispatchEvent(new CustomEvent('spaps:persona-change', { detail }));
+    }
+  }
+
+  function onPersonaChange(callback) {
+    if (typeof callback !== 'function') {
+      return function noopUnsubscribe() {};
+    }
+
+    personaChangeListeners.push(callback);
+    return function unsubscribe() {
+      const index = personaChangeListeners.indexOf(callback);
+      if (index >= 0) personaChangeListeners.splice(index, 1);
+    };
+  }
+
   function clearPersonaBrowserStorage() {
     PERSONA_LOCAL_STORAGE_KEYS.forEach((key) => {
       localStorage.removeItem(key);
@@ -1441,6 +1506,7 @@ function buildDevAuthBridgeScript(config) {
     localStorage.setItem(STORAGE_KEYS.profile, JSON.stringify(persona.user));
     localStorage.setItem(STORAGE_KEYS.roles, JSON.stringify(persona.user.roles || []));
     localStorage.setItem(STORAGE_KEYS.entitlements, JSON.stringify(persona.entitlement_keys || []));
+    localStorage.setItem(STORAGE_KEYS.scenario, JSON.stringify(persona.scenario || {}));
     localStorage.setItem(STORAGE_KEYS.application, JSON.stringify(persona.application || CONFIG.application));
     localStorage.setItem(STORAGE_KEYS.runtime, JSON.stringify({
       auth_mode: CONFIG.auth_mode,
@@ -1458,11 +1524,21 @@ function buildDevAuthBridgeScript(config) {
   }
 
   function clearSession() {
-    [ACTIVE_PERSONA_KEY, STORAGE_KEYS.persona, STORAGE_KEYS.profile, STORAGE_KEYS.roles, STORAGE_KEYS.entitlements, STORAGE_KEYS.application, STORAGE_KEYS.runtime, STORAGE_KEYS.selector, TOKEN_USER_KEY, TOKEN_ACCESS_KEY, TOKEN_REFRESH_KEY, LEGACY_USER_KEY, ...PERSONA_LOCAL_STORAGE_KEYS].forEach((key) => {
+    [ACTIVE_PERSONA_KEY, STORAGE_KEYS.persona, STORAGE_KEYS.profile, STORAGE_KEYS.roles, STORAGE_KEYS.entitlements, STORAGE_KEYS.scenario, STORAGE_KEYS.application, STORAGE_KEYS.runtime, STORAGE_KEYS.selector, TOKEN_USER_KEY, TOKEN_ACCESS_KEY, TOKEN_REFRESH_KEY, LEGACY_USER_KEY, ...PERSONA_LOCAL_STORAGE_KEYS].forEach((key) => {
       localStorage.removeItem(key);
     });
   }
 
+  function switchPersona(code, options) {
+    const nextPersona = getPersonaByCode(code);
+    if (!nextPersona) return null;
+    const previousPersona = getCurrentPersona();
+    persistPersona(nextPersona);
+    emitPersonaChange(previousPersona, nextPersona);
+    if (!options || options.reload !== false) window.location.reload();
+    return nextPersona;
+  }
+
   function response(body, status) {
     return Promise.resolve(new Response(JSON.stringify(body), {
       status: status || 200,
@@ -1625,10 +1701,7 @@ function buildDevAuthBridgeScript(config) {
     button.textContent = 'Switch';
     button.style.cssText = 'background:#f59e0b;color:#111827;border:0;border-radius:8px;padding:4px 8px;cursor:pointer;font-weight:600;';
     button.onclick = function () {
-      const nextPersona = getPersonaByCode(select.value);
-      if (!nextPersona) return;
-      persistPersona(nextPersona);
-      window.location.reload();
+      switchPersona(select.value);
     };
 
     container.appendChild(label);
@@ -1648,20 +1721,17 @@ function buildDevAuthBridgeScript(config) {
         code: persona.code,
         display_name: persona.display_name,
         entitlements: persona.entitlement_keys,
-        roles: persona.user.roles || []
+        roles: persona.user.roles || [],
+        scenario: persona.scenario || {}
       }));
     },
     getCurrentPersona: getCurrentPersona,
     getCurrentUser: function () {
       return getCurrentPersona().user;
     },
-    switchPersona: function (code, options) {
-      const nextPersona = getPersonaByCode(code);
-      if (!nextPersona) return null;
-      persistPersona(nextPersona);
-      if (!options || options.reload !== false) window.location.reload();
-      return nextPersona;
-    },
+    getScenario: getScenario,
+    onPersonaChange: onPersonaChange,
+    switchPersona: switchPersona,
     clearSession: clearSession,
     installFetchBridge: installFetchBridge
   };
@@ -1699,6 +1769,10 @@ function buildStorageStateArtifact(appConfig, persona, rolesConfig, entitlements
       name: FIXTURE_KEYS.entitlements,
       value: stringifyStorageValue(entitlementsConfig.grants?.[persona.code] || []),
     },
+    {
+      name: FIXTURE_KEYS.scenario,
+      value: stringifyStorageValue(persona.scenario || {}),
+    },
     {
       name: FIXTURE_KEYS.application,
       value: stringifyStorageValue(application),