@kieransimkin/dancemoves 3.1.22 → 3.2.0

package/README.md

@@ -1,5 +1,17 @@
 # DanceMoves
 
+**3.2.0** adds native, non-looping playback of StemLab/DanceRudiments audio-derived movement recordings.  `runtime.recordings` composes the existing audio clock, shared player mapping, accessibility preferences and lifecycle. Captured BPM must match page metadata; samples retain their original integer-pip clock and never wrap. See [recording playback](docs/audio-recording-playback.md).
+
+
+**3.1.23** secures WordPress motion-capture writes with authenticated
+`manage_options` authorization. The private capture administration UI uses the
+same capability. Published tokens no longer authorize uploads; cookie clients
+send a fresh WordPress REST nonce and same-origin credentials, and administrators
+have separate bounded upload quotas. Local recording/download stays available
+without upload authorization. See the [capture contract](docs/api/wordpress.md#motion-capture-rest-api).
+The real WordPress integration test reports its executed assertion count;
+CI rejects a missing or zero-count summary as well as any failed check.
+
 **3.1.22** fixes WordPress.org submission metadata: the Author URI points to
 [Kieran's website](https://kieransimkin.co.uk/), separately from the plugin
 homepage. The release checker rejects duplicate plugin/author URLs before
@@ -602,7 +614,8 @@ const example = {schema:'ks-epk-motion-recording/v1', samples:[{t:0,beta:10,gamm
 inspect(example);
 // The local simulator uses /examples/wordpress/api/capture, never /wp-json/… .
 // For actual captures, follow docs/api/wordpress.md and the private sensor harness.
-// The existing source token is not strong authentication; never embed it in public examples.
+// Uploads require administrator authorization and a fresh WordPress REST nonce.
+// Keep real session nonces out of static examples and source control.
 ```
 
 [Run the example](examples/wordpress/capture.html) · [Read its complete source](examples/wordpress/demos/capture.mjs).

package/docs/api/surface.json

@@ -7,6 +7,16 @@
   "effects_version": "3.1.13",
   "effects_reviewed_on": "2026-10-08",
   "inventory_method": "Manual comparison with the pinned source exports and PHP declarations; symbol-presence validation is not runtime coverage.",
+  "wordpress_capture_security": {
+    "version": "3.1.23",
+    "reviewed_on": "2026-10-15",
+    "scope": "Current capture contract supersedes the historical 2.8.0 capture authorization, quota and post-type capability description; pinned baseline symbols and source hashes below remain historical evidence.",
+    "authorization": "WordPress-authenticated current_user_can('manage_options'); cookie REST nonces are checked by WordPress core",
+    "removed_constants": ["KS_EPK_MOTION_CAPTURE_TOKEN"],
+    "quota": "ks_motion_user_<authenticated user ID>, eight accepted checks per ten-minute expiry",
+    "private_capture_capability": "manage_options",
+    "reference": "wordpress.md#motion-capture-rest-api"
+  },
   "source_blobs": {
     "kieran-epk-device-orientation.php": "b374690a0c141aa1f870bf1084a0a0b34c25abe5",
     "assets/dance-moves-core.js": "3d975c7a3b380f9c99a62f7deade14df4b746929",

package/docs/api/wordpress.md

@@ -15,7 +15,7 @@ registration, rendering or save callbacks manually.
 | --- | --- |
 | `DANCE_MOVES_VERSION` | `2.8.0` |
 | `KS_EPK_ORIENTATION_VERSION` | Alias of `DANCE_MOVES_VERSION`. |
-| `KS_EPK_MOTION_CAPTURE_TOKEN` | Existing fixed capture submission token; deliberately not reproduced here. It is in public source and is **not a deployment secret**. See the capture security section. |
+| `KS_EPK_MOTION_CAPTURE_TOKEN` | Removed in 3.1.23. No fixed/published token authorizes capture writes. See the current capture security section. |
 | `DANCE_MOVES_META_BPM` | `_dance_moves_bpm` |
 | `DANCE_MOVES_META_LYRIC_TIMING` | `_dance_moves_lyric_timing_id` |
 | `DANCE_MOVES_META_CUE_TIMING` | `_dance_moves_cue_timing_id` |
@@ -172,7 +172,7 @@ The full validator runs when the Page editor saves the selected attachment.
 ```text
 POST <WordPress REST root>/ks-epk-motion/v1/capture
 Content-Type: application/json
-X-KS-Motion-Token: <operator-supplied value; not reproduced here>
+X-WP-Nonce: <fresh wp_rest nonce for the signed-in administrator session>
 ```
 
 Implemented by `ks_epk_motion_register_rest_route()` using
@@ -180,23 +180,48 @@ Implemented by `ks_epk_motion_register_rest_route()` using
 `ks_epk_motion_capture_permission(WP_REST_Request $request)` and handler
 `ks_epk_motion_store_capture(WP_REST_Request $request)`.
 
-Permission processing, in order:
+In 3.1.23, permission processing is:
+
+1. WordPress authenticates the request before the permission callback. Cookie
+   clients send same-origin credentials and a fresh `wp_rest` nonce in
+   `X-WP-Nonce`; WordPress validates that nonce. Missing/expired cookie nonces
+   cannot establish administrator authorization. Standard WordPress Application
+   Password authentication over HTTPS may also establish the current user;
+   this plugin does not create or store those credentials.
+2. Require `current_user_can('manage_options')`. Anonymous requests return 401;
+   authenticated callers lacking that capability return 403. The former
+   `X-KS-Motion-Token` header is ignored and its public constant is removed.
+3. When `get_http_origin()` supplies an origin, require it to equal `home_url()`
+   after trailing-slash removal. A missing Origin is allowed only after genuine
+   WordPress authentication/authorization, for example an authorized API client.
+4. Rate-limit by authenticated user ID, using `ks_motion_user_<id>`. Eight
+   accepted permission checks are allowed before 429. Each allowed check writes
+   a ten-minute expiry; a later-invalid payload still consumes a check. Denied
+   callers and other administrators cannot exhaust an administrator's quota.
+
+The development lab's static HTML carries no real nonce. Populate its
+`ksMotionCaptureConfig.restNonce` from the current administrator session, not a
+committed value. A registered harness on an authenticated WordPress admin screen
+can use the normal script configuration route:
 
-1. Compare the supplied header with the fixed token using `hash_equals()`.
-2. When `get_http_origin()` returns an origin, require it to equal `home_url()`
-   after trailing-slash removal. A missing Origin is **not rejected**.
-3. Rate-limit by a transient keyed from MD5 of `REMOTE_ADDR` (or `'unknown'`).
-   Eight accepted permission checks are allowed before a 429. Each allowed check
-   writes a new ten-minute expiry; this is not a rigorously sliding-window quota.
-   A later-invalid payload still consumes a permission-check attempt.
+```php
+if (current_user_can('manage_options')) {
+    // Run after registering/enqueuing your own capture harness script.
+    wp_localize_script('your-capture-harness', 'ksMotionCaptureConfig', array(
+        'endpoint' => esc_url_raw(rest_url('ks-epk-motion/v1/capture')),
+        'restNonce' => wp_create_nonce('wp_rest'),
+    ));
+}
+```
 
-**Security limitation:** the token is embedded in this public repository. The
-endpoint does not require a logged-in user, a WordPress capability or a WordPress
-nonce. Origin checking and a shared IP transient do not turn a published constant
-into authentication. Do not document this as a secure secret-protected upload
-service. Restrict/disable access or implement genuine authenticated capture
-submission before relying on it in a new deployment. This documentation patch
-does not change the endpoint's security model or rotate its constant.
+The capture client sends `credentials: 'same-origin'` and rejects a different
+endpoint origin before transmitting a nonce or recording. A missing nonce leaves
+local recording/download available and displays an accurate upload hold. After
+a session/nonce expires, reload the authorized configuration before retrying.
+Sensor consent and the explicit upload button remain separate requirements.
+See WordPress's [REST authentication](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/)
+and [permission callback](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/#permissions-callback)
+documentation. No custom authentication mechanism is added.
 
 ### Request shape
 
@@ -275,9 +300,9 @@ Success returns a normal REST response (no explicit 201 status is set):
 
 | HTTP status | Error code | Meaning |
 | --- | --- | --- |
-| 403 | `ks_motion_forbidden` | Missing/wrong token. |
+| 401 / 403 | `ks_motion_forbidden` | WordPress caller is anonymous / lacks `manage_options`. |
 | 403 | `ks_motion_origin` | Supplied origin does not match the site. |
-| 429 | `ks_motion_rate` | Permission-check quota exhausted. |
+| 429 | `ks_motion_rate` | This administrator's permission-check quota exhausted. |
 | 400 | `ks_motion_schema` | Missing/wrong schema or nonarray JSON payload. |
 | 400 | `ks_motion_samples` | Missing/nonarray samples or input count outside 1–500. |
 | 400 | `ks_motion_invalid_samples` | At least one required sample field is invalid. |
@@ -292,9 +317,12 @@ A successful record is a `private` post of type `ks_motion_capture`, titled
 `Phone motion capture <site-local date/time>`, with the cleaned JSON in
 `post_content`. Extra metadata: `_ks_motion_passed` (`'1'`/`'0'`),
 `_ks_motion_sample_count`, and `_ks_motion_sha256` (hash of stored encoded JSON).
-The post type has a Tools-menu UI, title/editor support, `public: false`,
-`show_in_rest: false`, and default mapped post capabilities; no custom
-administrator-only capability scheme is defined.
+The post author is the authenticated administrator ID. The post type has a
+Tools-menu UI, title/editor support, `public: false`, and `show_in_rest: false`.
+In 3.1.23 its read, create, edit and delete capabilities all require
+`manage_options`, with generic post meta-capability mapping disabled. Ordinary
+editors/authors cannot acquire access to private sensor captures through their
+normal post-editing capabilities. Retention remains an explicit operator duty.
 
 There is **no plugin GET/list/delete capture REST route, retention job, automatic
 capture upload, or cryptographic proof of native sensor provenance**. Private
@@ -323,6 +351,24 @@ available. Do not assume a root exists merely because the shared script loaded.
 
 ## Registered hooks and callback reference
 
+### Project prefixes and compatibility
+
+Production PHP declarations use `dance_moves_` / `ks_epk_` functions and
+`DANCE_MOVES_` / `KS_EPK_` constants. Plugin-owned metadata, transients, post
+types, REST namespaces and asset handles use the existing `dance_moves`,
+`dance-moves`, `ks_motion`, `ks-epk-motion` or `ks-epk-device-orientation`
+prefixes. Localized JavaScript configuration uses the named `danceMoves*` and
+`ksEpkOrientationConfig` objects. WordPress core hook names in the table below
+are consumed hooks; they must retain their core names.
+
+These names remain for installed-site compatibility. In 3.1.23 the obsolete
+public token constant is removed and the authenticated quota uses the prefixed
+`ks_motion_user_<id>` transient. The declaration-prefix regression and capture
+authorization/client tests run in the existing legacy test gate. Hosted CI also
+exercises real WordPress core nonce validation, roles, REST dispatch, database
+storage and capability mapping on a disposable site. It does not use a live
+installation or claim physical phone acceptance.
+
 These are WordPress hooks **consumed** by the plugin, not plugin-defined extension
 hooks. Default priority is 10 unless shown. No `apply_filters('dance_moves_...')`
 or `do_action('dance_moves_...')` extension contract is exposed in this baseline.

package/docs/audio-recording-playback.md

@@ -0,0 +1,56 @@
+# Audio-derived recording playback
+
+DanceMoves 3.2.0 adds `runtime.recordings` for the bounded `dancerudiments.recording`
+v1 JSON format exported by StemLab and DanceRudiments 0.3.0. Named native patterns
+continue to loop at their own periods. Recordings retain their captured origin,
+64-pip resolution, named dimensions and exact extent; they never wrap or interpolate.
+
+```js
+const recording = await runtime.recordings.load('/approved-motion.json');
+const motion = runtime.recordings.animate({
+  id: 'subject:recording', root, target, audio,
+  recording,
+  render({values, reason}) {
+    // Map bounded native samples to the existing subject's appearance.
+    // A CSSOM rule avoids high-frequency inline-style mutation observers.
+    rule.style.setProperty('--subject-angle', `${values[0] * 6}deg`);
+  }
+});
+await motion.ready;
+motion.setEnabled(false); // neutral values, preserving the captured clock
+motion.setEnabled(true);
+motion.destroy();
+```
+
+The controller composes the existing native DanceMoves audio scheduler and its
+shared-player mapping. Pause holds the source pose; seeking reconstructs it.
+Reduced motion, forced colours and explicit disable output zeroes. Hidden and
+offscreen subjects suspend through the existing lifecycle. Positions outside the
+recording emit zeroes with `reason: 'outside-recording'`; seeking back into the
+capture resumes its exact native sample. Runtime disposal destroys all recording
+controllers, including pending native loads. Use `pause()`, `resume()`, `refresh()`,
+`snapshot()`, `recordings.get(id)` and `recordings.snapshot()` for ownership and QA.
+
+The recording BPM must match the authoritative runtime/page BPM. A controller
+cannot override tempo, rate, phase or clock. BPM provenance and phase provenance
+remain separate. The page's WordPress EPK Timing metadata remains the only source
+for lyric/cue attachments; a movement recording never replaces those fields.
+Use the exact track/master, same-clock stem provenance and original capture origin.
+StemLab owns separation, filtering and smoothing; this player performs no DSP.
+All smoothing variants should use a fixed reference scale for a fair comparison.
+
+The sampler is the official native C++/WebAssembly accessor from DanceRudiments
+0.3.0. There is no JavaScript movement fallback. Its embedded binary SHA-256 is
+`d4cd976156860aa7a5c9665b27d2fda3cf6a0fa0da3dc0b9df365e425f1c6e29`, built from
+upstream `include/dancerudiments/recording_view.hpp` SHA-256
+`19dd73a150a82c4d9074fe4b9ba4c2f09d41e206028a6a6dc922d94e00dc4b8d` and
+`tools/recording_wasm.cpp` SHA-256
+`f4713cc7c773fa065715383fc68dccd91398fff08cd89167c5f24e64c0cecea9`.
+See the [upstream recording contract](https://github.com/kieransimkin/DanceRudiments/blob/v0.3.0/docs/recordings.md).
+The existing bundled named catalogue and its separate version are unchanged.
+
+Inputs are limited to 64 MiB JSON, 8,388,608 finite values in [-1,1], 1..64 unique
+named dimensions and signed 32-bit integer pip bounds. Loading fails closed for
+bad UTF-8, schema, samples, HTTP responses, mismatched BPM or unavailable WASM.
+Treat `ready` rejection as an unavailable motion state and retain static content.
+These source/build changes do not deploy a WordPress plugin or page.

package/lib/build-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema": "dancemoves-library-build/v1",
   "name": "@kieransimkin/dancemoves",
-  "version": "3.1.22",
+  "version": "3.2.0",
   "homepage": "https://kieransimkin.co.uk/my-songs/",
   "files": [
     {
@@ -31,23 +31,23 @@
     },
     {
       "path": "dancemoves.min.js",
-      "bytes": 212321,
-      "sha256": "36651cd57003477609ac0024c66ae69698cf51ef1ae083f3dd25e7a7ad41e3c4"
+      "bytes": 218383,
+      "sha256": "9a9afad98cbf15d3c8394a54809596d1ffe784f5ac7ca13484186ace3eb93661"
     },
     {
       "path": "index.cjs",
-      "bytes": 361185,
-      "sha256": "1f02fb91fa046ac132a0757ceed994843adae20728fbb80327a1ea6c314a515a"
+      "bytes": 370576,
+      "sha256": "ca7ed8da52270ee4a17f94672121f4182fa5cc8c5964c8d095a682978d1b4981"
     },
     {
       "path": "index.d.ts",
-      "bytes": 13718,
-      "sha256": "82ec16610754f0237cd91e2a7a7ce4f6fe17617d8a61b78d089143e9fdb142e4"
+      "bytes": 14929,
+      "sha256": "477a8d665f245dbcff92cdc17372f39b54dbe3f9392695a00773f43b92288914"
     },
     {
       "path": "index.mjs",
-      "bytes": 360040,
-      "sha256": "1766fb4365f13191b75dc77ac01c9e51c8e8250e8408c34a7d7bf19ce77fe32b"
+      "bytes": 369431,
+      "sha256": "6edacb0ded30311fc26bb80e86c772ba362c1b60c54a68b5ebaa2d3eb484ac16"
     },
     {
       "path": "react.cjs",
@@ -106,8 +106,8 @@
     },
     {
       "path": "wordpress.js",
-      "bytes": 211126,
-      "sha256": "fcea9c493f3e895320eb15673580cdfebd6b8fd333cd90e2a11c0054fbe8317d"
+      "bytes": 217191,
+      "sha256": "1b02054111edf66b3a5766c7da74291fe597d2ed3ac7a89f0f282cfb99c415df"
     }
   ]
 }