@storystick/preview 0.0.0-stage → 0.2.0-rc.1

package/dist/validators.js

@@ -0,0 +1,110 @@
+/**
+ * Iframe-side preview-envelope validators (ADR-087 §3.2).
+ *
+ * Thin wrapper around `validatePreviewEnvelope` from
+ * `@storystick/transport-allowlist` (the foundation Lane C shipped).
+ * Adds the iframe-side context checks the foundation deliberately left out:
+ *
+ *   - `sessionId` and `projectId` match the iframe's known values
+ *     (they should never change mid-session).
+ *   - `event.origin === parentOrigin` once the parent origin is
+ *     learned (see "learn-and-lock" comment below).
+ *
+ * The foundation validator owns structure + anti-replay base
+ * (`MAX_ENVELOPE_AGE_MS`) + normative error wording. This module owns
+ * everything that needs *iframe context*: identity and the locked parent
+ * origin.
+ *
+ * Returning a discriminated `{ ok, ... }` keeps the call-site clean —
+ * the consumer handles `ok: false` by either ignoring the message
+ * (stale / mis-correlated) or transitioning to `error` (auth failed).
+ */
+import { validatePreviewEnvelope, } from '@storystick/transport-allowlist';
+/**
+ * Validate an incoming `navigate` envelope against the locked parent
+ * origin and the iframe's known sessionId / projectId. Navigate
+ * messages are unsolicited (no pending request to correlate against)
+ * — we only check origin lock + identity binding.
+ *
+ * **Pre-lock policy (codex Lane D round 1 P1 fix)** : `parentOrigin
+ * === null` means the iframe has not yet locked Studio's origin.
+ * Navigate messages received in that window are rejected
+ * unconditionally (`origin-mismatch`). Without this, any same-host
+ * script with a valid envelope shape could drive `history.pushState`
+ * on the iframe before the legitimate Studio handshake finishes.
+ * The identity broadcast is the only origin-learning path; navigation MUST
+ * wait for that lock.
+ */
+export function validateNavigate(raw, eventOrigin, knownSessionId, knownProjectId, parentOrigin, now = Date.now()) {
+    const base = validatePreviewEnvelope(raw, now);
+    if (!base.ok)
+        return { ok: false, reason: 'envelope-invalid' };
+    if (base.message.type !== 'storystick.preview.navigate') {
+        return { ok: false, reason: 'wrong-message-type' };
+    }
+    // Reject pre-lock + reject post-lock origin mismatch.
+    if (parentOrigin === null || eventOrigin !== parentOrigin) {
+        return { ok: false, reason: 'origin-mismatch' };
+    }
+    if (base.message.sessionId !== knownSessionId) {
+        return { ok: false, reason: 'session-id-mismatch' };
+    }
+    if (base.message.projectId !== knownProjectId) {
+        return { ok: false, reason: 'project-id-mismatch' };
+    }
+    return { ok: true, envelope: base.message };
+}
+export function validateOverlayMap(raw, eventOrigin, knownSessionId, knownProjectId, parentOrigin, now = Date.now()) {
+    const base = validatePreviewEnvelope(raw, now);
+    if (!base.ok)
+        return { ok: false, reason: 'envelope-invalid' };
+    if (base.message.type !== 'storystick.preview.overlay-map') {
+        return { ok: false, reason: 'wrong-message-type' };
+    }
+    if (parentOrigin === null || eventOrigin !== parentOrigin) {
+        return { ok: false, reason: 'origin-mismatch' };
+    }
+    if (base.message.sessionId !== knownSessionId) {
+        return { ok: false, reason: 'session-id-mismatch' };
+    }
+    if (base.message.projectId !== knownProjectId) {
+        return { ok: false, reason: 'project-id-mismatch' };
+    }
+    return { ok: true, envelope: base.message };
+}
+export function validateOverlayClear(raw, eventOrigin, knownSessionId, knownProjectId, parentOrigin, now = Date.now()) {
+    const base = validatePreviewEnvelope(raw, now);
+    if (!base.ok)
+        return { ok: false, reason: 'envelope-invalid' };
+    if (base.message.type !== 'storystick.preview.overlay-clear') {
+        return { ok: false, reason: 'wrong-message-type' };
+    }
+    if (parentOrigin === null || eventOrigin !== parentOrigin) {
+        return { ok: false, reason: 'origin-mismatch' };
+    }
+    if (base.message.sessionId !== knownSessionId) {
+        return { ok: false, reason: 'session-id-mismatch' };
+    }
+    if (base.message.projectId !== knownProjectId) {
+        return { ok: false, reason: 'project-id-mismatch' };
+    }
+    return { ok: true, envelope: base.message };
+}
+export function validatePreviewV2RevealSource(raw, eventOrigin, knownSessionId, knownProjectId, parentOrigin, now = Date.now()) {
+    const base = validatePreviewEnvelope(raw, now);
+    if (!base.ok)
+        return { ok: false, reason: 'envelope-invalid' };
+    if (base.message.type !== 'storystick.preview.v2.reveal-source') {
+        return { ok: false, reason: 'wrong-message-type' };
+    }
+    if (parentOrigin === null || eventOrigin !== parentOrigin) {
+        return { ok: false, reason: 'origin-mismatch' };
+    }
+    if (base.message.sessionId !== knownSessionId) {
+        return { ok: false, reason: 'session-id-mismatch' };
+    }
+    if (base.message.projectId !== knownProjectId) {
+        return { ok: false, reason: 'project-id-mismatch' };
+    }
+    return { ok: true, envelope: base.message };
+}

package/package.json

@@ -1,6 +1,213 @@
 {
   "name": "@storystick/preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-rc.1",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime/store": {
+      "types": "./dist/runtime/store.d.ts",
+      "import": "./dist/runtime/store.js"
+    },
+    "./runtime/request-id": {
+      "types": "./dist/runtime/request-id.d.ts",
+      "import": "./dist/runtime/request-id.js"
+    },
+    "./runtime/authority": {
+      "types": "./dist/runtime/authority-store.d.ts",
+      "import": "./dist/runtime/authority-store.js"
+    },
+    "./overlay-label": {
+      "types": "./dist/overlay-label.d.ts",
+      "import": "./dist/overlay-label.js"
+    },
+    "./select-cursor": {
+      "types": "./dist/select-cursor.d.ts",
+      "import": "./dist/select-cursor.js"
+    },
+    "./runtime/boot": {
+      "types": "./dist/runtime/boot.d.ts",
+      "import": "./dist/runtime/boot.js"
+    },
+    "./runtime/perf-metrics": {
+      "types": "./dist/runtime/perf-metrics.d.ts",
+      "import": "./dist/runtime/perf-metrics.js"
+    },
+    "./runtime/live-query-overlay": {
+      "types": "./dist/runtime/live-query-overlay.d.ts",
+      "import": "./dist/runtime/live-query-overlay.js"
+    },
+    "./refresh-policy": {
+      "types": "./dist/refresh-policy.d.ts",
+      "import": "./dist/refresh-policy.js"
+    },
+    "./runtime/emit-runtime-error": {
+      "types": "./dist/runtime/emit-runtime-error.d.ts",
+      "import": "./dist/runtime/emit-runtime-error.js"
+    },
+    "./runtime/workspace-shortcuts": {
+      "types": "./dist/runtime/workspace-shortcuts.d.ts",
+      "import": "./dist/runtime/workspace-shortcuts.js"
+    },
+    "./runtime/momentary-navigate": {
+      "types": "./dist/runtime/momentary-navigate.d.ts",
+      "import": "./dist/runtime/momentary-navigate.js"
+    },
+    "./runtime/content-refresh": {
+      "types": "./dist/runtime/content-refresh.d.ts",
+      "import": "./dist/runtime/content-refresh.js"
+    },
+    "./runtime/standalone-overlays": {
+      "types": "./dist/runtime/standalone-overlay-controller.d.ts",
+      "import": "./dist/runtime/standalone-overlay-controller.js"
+    },
+    "./runtime/invalidation": {
+      "types": "./dist/runtime/invalidation-adapter.d.ts",
+      "import": "./dist/runtime/invalidation-adapter.js"
+    },
+    "./dev/suspicious-codeword-detector": {
+      "types": "./dist/dev/suspicious-codeword-detector.d.ts",
+      "development": "./dist/dev/suspicious-codeword-detector.js",
+      "default": "./dist/dev/suspicious-codeword-detector.noop.js"
+    },
+    "./channel-taxonomy": {
+      "types": "./dist/channel-taxonomy.d.ts",
+      "import": "./dist/channel-taxonomy.js"
+    },
+    "./session-projections": {
+      "types": "./dist/session-projections.d.ts",
+      "import": "./dist/session-projections.js"
+    },
+    "./nav-handler": {
+      "types": "./dist/nav-handler.d.ts",
+      "import": "./dist/nav-handler.js"
+    },
+    "./router-subscriber": {
+      "types": "./dist/router-subscriber.d.ts",
+      "import": "./dist/router-subscriber.js"
+    },
+    "./identity/preview-cookie": {
+      "types": "./dist/identity/preview-cookie.d.ts",
+      "import": "./dist/identity/preview-cookie.js"
+    },
+    "./identity/browser-context": {
+      "types": "./dist/identity/browser-context.d.ts",
+      "import": "./dist/identity/browser-context.js"
+    },
+    "./identity": {
+      "types": "./dist/identity/index.d.ts",
+      "import": "./dist/identity/index.js"
+    },
+    "./provenance": {
+      "types": "./dist/provenance/index.d.ts",
+      "import": "./dist/provenance/index.js"
+    },
+    "./provenance/richtext-slice-embed-address": {
+      "types": "./dist/provenance/richtext-slice-embed-address.d.ts",
+      "import": "./dist/provenance/richtext-slice-embed-address.js"
+    },
+    "./authoring/runtime-contract": {
+      "types": "./dist/authoring/runtime-contract.d.ts",
+      "import": "./dist/authoring/runtime-contract.js"
+    },
+    "./page-presentation": {
+      "types": "./dist/page-presentation.d.ts",
+      "import": "./dist/page-presentation.js"
+    },
+    "./sdk-error-copy": {
+      "types": "./dist/sdk-error-copy.d.ts",
+      "import": "./dist/sdk-error-copy.js"
+    },
+    "./session-subscriber": {
+      "types": "./dist/session-subscriber.d.ts",
+      "import": "./dist/session-subscriber.js"
+    },
+    "./provenance/source-registry": {
+      "types": "./dist/provenance/source-registry.d.ts",
+      "import": "./dist/provenance/source-registry.js"
+    },
+    "./runtime/preview-transition-state": {
+      "types": "./dist/runtime/preview-transition-state.d.ts",
+      "import": "./dist/runtime/preview-transition-state.js"
+    },
+    "./runtime/preview-perspective-intent-state": {
+      "types": "./dist/runtime/preview-perspective-intent-state.d.ts",
+      "import": "./dist/runtime/preview-perspective-intent-state.js"
+    },
+    "./runtime/preview-perspective-alignment": {
+      "types": "./dist/runtime/preview-perspective-alignment.d.ts",
+      "import": "./dist/runtime/preview-perspective-alignment.js"
+    },
+    "./reveal-target": {
+      "types": "./dist/reveal-target.d.ts",
+      "import": "./dist/reveal-target.js"
+    },
+    "./framework/*": {
+      "types": "./dist/framework/*.d.ts",
+      "import": "./dist/framework/*.js"
+    },
+    "./routes": {
+      "types": "./dist/route-paths.d.ts",
+      "import": "./dist/route-paths.js"
+    },
+    "./server/*": {
+      "types": "./dist/server/*.d.ts",
+      "import": "./dist/server/*.js"
+    },
+    "./provenance/render-context": {
+      "types": "./dist/provenance/render-context.d.ts",
+      "import": "./dist/provenance/render-context.js"
+    },
+    "./provenance/slice-model": {
+      "types": "./dist/provenance/slice-model.d.ts",
+      "import": "./dist/provenance/slice-model.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "PUBLIC-API.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false,
+    "tag": "beta"
+  },
+  "dependencies": {
+    "convex": "1.42.3",
+    "@storystick/client": "0.2.0-rc.1",
+    "@storystick/transport-allowlist": "0.1.0-rc.1",
+    "@storystick/types": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "^6.2.5",
+    "jsdom": "^29.0.2",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1",
+    "@types/node": "^22.13.10"
+  },
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstorystick/storystick.git",
+    "directory": "packages/preview"
+  },
+  "homepage": "https://storystick.app",
+  "bugs": {
+    "url": "https://storystick.app"
+  },
+  "scripts": {
+    "build": "node ../../scripts/package-dist.mjs clean && tsc && node ../../scripts/package-dist.mjs seal",
+    "test": "vitest run",
+    "test:dist-fresh": "node scripts/assert-dist-fresh.mjs",
+    "test:watch": "vitest"
+  }
 }