rampway 0.3.0 → 0.3.1

package/build/src/velocious/sanitize.js

@@ -0,0 +1,154 @@
+// @ts-check
+const MAX_STRING_LENGTH = 4000;
+const MAX_DEPTH = 20;
+const MAX_COLLECTION_ENTRIES = 100;
+const MAX_VISITED_VALUES = 1000;
+const MAX_SERIALIZED_BYTES = 64 * 1024;
+const MAX_PREVIEW_LENGTH = 8000;
+const REDACTED = "[redacted]";
+const TRUNCATION_MARKER = "[truncated]";
+const TRUNCATED_VALUE = Symbol("truncated");
+/** @typedef {{visited: number}} SanitizerState */
+/**
+ * @param {string} value - Value to redact.
+ * @param {string[]} secrets - Exact configured secrets.
+ * @returns {string} Redacted and bounded value.
+ */
+function redactString(value, secrets) {
+    let result = value;
+    for (const secret of secrets) {
+        if (secret.length > 0)
+            result = result.split(secret).join(REDACTED);
+    }
+    return result.length > MAX_STRING_LENGTH ? `${result.slice(0, MAX_STRING_LENGTH)}…` : result;
+}
+/**
+ * Converts an integration value to bounded JSON data while redacting secrets
+ * in values and keys. Colliding redacted keys are retained with stable suffixes.
+ *
+ * @param {unknown} value - Integration value.
+ * @param {string[]} secrets - Secrets to remove.
+ * @param {number} [depth] - Current depth.
+ * @returns {any} JSON-safe value or undefined.
+ */
+export function sanitizeAdapterValue(value, secrets, depth = 0) {
+    const sanitized = sanitizeValue(value, secrets, depth, { visited: 0 });
+    if (sanitized === undefined)
+        return undefined;
+    if (sanitized === TRUNCATED_VALUE)
+        return { reason: "Sanitized output exceeded traversal limits", truncated: true };
+    const serialized = JSON.stringify(sanitized);
+    if (Buffer.byteLength(serialized) <= MAX_SERIALIZED_BYTES)
+        return sanitized;
+    return {
+        preview: serialized.slice(0, MAX_PREVIEW_LENGTH),
+        reason: `Sanitized output exceeded ${MAX_SERIALIZED_BYTES} bytes`,
+        truncated: true
+    };
+}
+/**
+ * @param {unknown} value - Integration value.
+ * @param {string[]} secrets - Secrets to remove.
+ * @param {number} depth - Current depth.
+ * @param {SanitizerState} state - Shared traversal budget.
+ * @returns {any} JSON-safe value, undefined, or the truncation sentinel.
+ */
+function sanitizeValue(value, secrets, depth, state) {
+    if (state.visited >= MAX_VISITED_VALUES || depth > MAX_DEPTH)
+        return TRUNCATED_VALUE;
+    state.visited++;
+    if (value === null)
+        return null;
+    if (typeof value === "string")
+        return redactString(value, secrets);
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "boolean")
+        return value;
+    if (Array.isArray(value)) {
+        const result = [];
+        let truncated = value.length > MAX_COLLECTION_ENTRIES;
+        const contentLimit = truncated ? MAX_COLLECTION_ENTRIES - 1 : value.length;
+        for (let index = 0; index < contentLimit; index++) {
+            const sanitized = sanitizeValue(value[index], secrets, depth + 1, state);
+            if (sanitized === TRUNCATED_VALUE) {
+                truncated = true;
+                break;
+            }
+            if (sanitized !== undefined)
+                result.push(sanitized);
+        }
+        if (truncated)
+            result.push(TRUNCATION_MARKER);
+        return result;
+    }
+    if (typeof value !== "object")
+        return undefined;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return undefined;
+    /** @type {Record<string, any>} */
+    const result = {};
+    const keys = [];
+    let truncated = false;
+    for (const key in value) {
+        if (!Object.hasOwn(value, key))
+            continue;
+        keys.push(key);
+        if (keys.length > MAX_COLLECTION_ENTRIES) {
+            truncated = true;
+            keys.length = MAX_COLLECTION_ENTRIES - 1;
+            break;
+        }
+    }
+    for (const key of keys) {
+        const sanitized = sanitizeValue(/** @type {Record<string, unknown>} */ (value)[key], secrets, depth + 1, state);
+        if (sanitized === TRUNCATED_VALUE) {
+            truncated = true;
+            break;
+        }
+        if (sanitized === undefined)
+            continue;
+        defineAvailableProperty(result, redactString(key, secrets), sanitized);
+    }
+    if (truncated)
+        defineAvailableProperty(result, TRUNCATION_MARKER, true);
+    return result;
+}
+/**
+ * Defines a property without dropping a colliding diagnostic key.
+ *
+ * @param {Record<string, any>} target - Sanitized object.
+ * @param {string} key - Desired key.
+ * @param {unknown} value - Sanitized value.
+ * @returns {void}
+ */
+function defineAvailableProperty(target, key, value) {
+    let availableKey = key;
+    let collision = 2;
+    while (Object.hasOwn(target, availableKey)) {
+        availableKey = `${key}#${collision}`;
+        collision++;
+    }
+    Object.defineProperty(target, availableKey, {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true
+    });
+}
+/**
+ * @param {unknown} error - Deployment failure.
+ * @param {string[]} secrets - Secrets to remove.
+ * @returns {{message: string, recovery: any}} Safe failure payload.
+ */
+export function sanitizeErrorPayload(error, secrets) {
+    const message = error instanceof Error ? error.message : String(error);
+    const recovery = error instanceof Error ? /** @type {Error & {recovery?: unknown}} */ (error).recovery : undefined;
+    const payload = sanitizeAdapterValue({ message, recovery }, secrets);
+    if (payload && typeof payload === "object" && typeof payload.message === "string") {
+        return { message: payload.message, recovery: payload.recovery };
+    }
+    return { message: "Deployment failure diagnostics were truncated", recovery: payload };
+}
+//# sourceMappingURL=sanitize.js.map

package/build/src/velocious/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../../src/velocious/sanitize.js"],"names":[],"mappings":"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"}

package/docs/docker-development-environment.md

@@ -0,0 +1,103 @@
+# Docker development environment
+
+Rampway has one canonical root development image and one persistent Compose service. The image is digest-pinned Ubuntu 26.04 LTS with exact NodeSource Node 24, a checksummed signing key, the universal coding/debugging baseline, and the current OpenCode, Codex, Claude Code, and official Kimi Code CLIs. The build is source-independent: `.dockerignore` closes the build context to the Dockerfile metadata, the image copies no repository content, and project dependencies are installed only inside the running service.
+
+## First use
+
+Prerequisites are Docker with Compose v2 and a dedicated UID/GID-1000 development home containing this checkout at `$DEV_HOME_PATH/rampway`.
+
+Copy the portable template and confirm its required read-only credential sources:
+
+```bash
+cp .env.example .env
+test -d "${GH_CONFIG_SOURCE_PATH:-$HOME/.config/gh}"
+test -f "${CODEX_AUTH_SOURCE_PATH:-$HOME/.codex/auth.json}"
+```
+
+Set `DEV_HOME_PATH` in `.env` to a dedicated home path containing this checkout at `$DEV_HOME_PATH/rampway`. Do not use an unrelated general host home or recursively change its ownership in the container. The environment template defaults to `/home/dev`; adjust it for any non-default host layout.
+
+Run the preparation helper to create the required mount-target parent directories with correct permissions, then start the persistent service and install locked dependencies:
+
+```bash
+scripts/prepare-dev-home.sh
+docker compose up --build --detach dev
+scripts/docker-run.sh npm ci
+```
+
+`scripts/docker-run.sh` uses `docker compose exec -T dev` and preserves every command argument exactly. The service must already be running. Dependencies, caches, the checkout, and ordinary tool state persist naturally under the complete `/home/dev` bind.
+
+## Isolation and mounts
+
+Compose declares the default project name `rampway`. Override it with `COMPOSE_PROJECT_NAME` (or `-p`) and use a distinct `DEV_HOME_PATH` for each concurrent instance. Run `scripts/prepare-dev-home.sh` to create required mount-target parent directories before the first start:
+
+```bash
+COMPOSE_PROJECT_NAME=rampway-review DEV_HOME_PATH=/srv/rampway-dev-homes/review \
+  scripts/prepare-dev-home.sh
+COMPOSE_PROJECT_NAME=rampway-review DEV_HOME_PATH=/srv/rampway-dev-homes/review \
+  docker compose up --build --detach dev
+```
+
+The `dev` service has exactly these mounts:
+
+- `${DEV_HOME_PATH:?Set DEV_HOME_PATH in .env}` at `/home/dev`;
+- `${GH_CONFIG_SOURCE_PATH:?Set GH_CONFIG_SOURCE_PATH in .env}` at `/home/dev/.config/gh`, read-only;
+- `${CODEX_AUTH_SOURCE_PATH:?Set CODEX_AUTH_SOURCE_PATH in .env}` at `/home/dev/.codex/auth.json`, read-only.
+
+The GitHub config directory is selected through `GH_CONFIG_DIR`. Only the narrow Codex auth file is authorized; SSH keys, Docker sockets, broad host auth mounts, and separate Claude/Kimi/OpenCode secret paths are not. The tracked topology also forbids source split mounts, named source/session volumes, fixed names/ports, privileged mode, sidecars, and container-side ownership fixups.
+
+Provider CLI installation is not provider authorization. Threadwire remains parent-owned and is resolved outside this service through bare unversioned `npx threadwire`; Rampway installs no global or project Threadwire package and tracks no provider workspace profile.
+
+## Static validation
+
+The dependency-free verifier checks the image pin, NodeSource verification, provider specs, complete apt baseline, non-root identity, exact mounts, fail-closed interpolation, closed build context, forbidden topology, ignored `.env`, and helper contract. Its focused tests also inject representative regressions:
+
+```bash
+npm run verify:docker-dev-environment
+npm run test:docker-dev-environment
+```
+
+## Docker-capable coordinator validation
+
+The bootstrap service has no Docker access. A coordinator must render Compose and build the image cleanly:
+
+```bash
+export COMPOSE_PROJECT_NAME=rampway-canonical-validation
+docker compose config --quiet
+docker compose config
+docker compose build --pull --no-cache dev
+docker compose up --detach dev
+docker compose exec -T dev sh -lc 'test "$HOME" = /home/dev && test "$PWD" = /home/dev/rampway && test "$(id -u)" = 1000 && test "$(id -g)" = 1000'
+docker compose exec -T dev npm ci
+docker compose exec -T dev npm run verify:docker-dev-environment
+```
+
+To prove two-instance isolation, prepare two UID/GID-1000 development homes with Rampway at `<home>/rampway`, start both, and compare their container IDs:
+
+```bash
+COMPOSE_PROJECT_NAME=rampway-isolation-a DEV_HOME_PATH=/srv/rampway-dev-homes/isolation-a docker compose up --build --detach dev
+COMPOSE_PROJECT_NAME=rampway-isolation-b DEV_HOME_PATH=/srv/rampway-dev-homes/isolation-b docker compose up --build --detach dev
+test "$(COMPOSE_PROJECT_NAME=rampway-isolation-a docker compose ps -q dev)" != "$(COMPOSE_PROJECT_NAME=rampway-isolation-b docker compose ps -q dev)"
+```
+
+For fresh cutover, provision a new dedicated home with Rampway already checked out at `<home>/rampway`, then perform a clean image build and dependency install:
+
+```bash
+export RAMPWAY_COMPOSE_PROJECT=rampway-cutover-fresh
+export RAMPWAY_DEV_HOME=/srv/rampway-dev-homes/cutover-fresh
+test -d "$RAMPWAY_DEV_HOME/rampway/.git"
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose build --pull --no-cache dev
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose up --build --detach dev
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose exec -T dev npm ci
+```
+
+For exact resume, reuse the retained home and project name without reinstalling or relocating state, then prove the same checkout revision is visible:
+
+```bash
+test -n "$RAMPWAY_COMPOSE_PROJECT"
+test -d "$RAMPWAY_DEV_HOME/rampway/.git"
+export RAMPWAY_EXPECTED_HEAD="$(git -C "$RAMPWAY_DEV_HOME/rampway" rev-parse HEAD)"
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose up --build --detach dev
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose exec -T -e RAMPWAY_EXPECTED_HEAD="$RAMPWAY_EXPECTED_HEAD" dev sh -lc 'test "$PWD" = /home/dev/rampway && test "$(git rev-parse HEAD)" = "$RAMPWAY_EXPECTED_HEAD"'
+```
+
+The obsolete `/workspace` and named-volume state is not imported. Verify the new service before stopping the old project; removal of old named volumes is a separate destructive coordinator decision.

package/docs/velocious-deployment-api.md

@@ -0,0 +1,189 @@
+# Velocious callable deployment API
+
+`rampway/velocious` is Rampway's authenticated deployment control plane for a
+Velocious application. Rampway owns every deployment-specific decision and
+calls its normal deploy lifecycle; Velocious supplies only route mounting,
+request/connection scopes, database persistence, background execution, and
+framework error events.
+
+The API accepts no command, path, repository, branch, environment value, log
+request, or arbitrary Git ref. A caller can select only a configured
+project/stage pair, an immutable lowercase 40-character commit SHA reachable
+from that target's approved release branch, and an idempotency key.
+The idempotency key must be a non-secret client-generated value of at most 255
+characters and must not contain any configured bearer token; matching is
+case-sensitive, and such requests are rejected with `422` before run lookup or
+persistence.
+
+## Install and mount
+
+Install Velocious in the application that mounts this optional integration.
+Rampway declares it as an optional peer so applications that only use the CLI
+do not acquire a web-framework dependency.
+
+```sh
+npm install rampway velocious
+```
+
+In the application's Velocious routes file:
+
+```js
+import Routes from "velocious/build/src/routes/index.js"
+import RampwayDeploymentApi from "rampway/velocious"
+import deploymentSecrets from "../config/secrets/deployments.js"
+
+const routes = new Routes()
+
+routes.draw((route) => {
+  route.mount(RampwayDeploymentApi, {
+    at: "/rampway/deployments",
+    accessTokens: deploymentSecrets.rampwayAccessTokens,
+    projects: {
+      "my-app": {
+        stages: {
+          production: {
+            configPath: "/srv/my-app/control/rampway.config.mjs",
+            releaseBranch: "main"
+          }
+        }
+      }
+    }
+  })
+})
+
+export default {routes}
+```
+
+`accessTokens` and every `configPath` are explicit backend configuration.
+Provision the secrets module outside source control using the application's
+normal secret mechanism. There is deliberately no environment-variable
+fallback. `configPath` must be absolute, and its selected Rampway stage must
+use `remote-git`; the deployment target must have Git access to the stage's
+configured repository. Every `releaseBranch` is checked against Git heads-ref
+rules during mounting, so invalid names such as a trailing dot or `.lock`
+component fail at startup rather than during deployment.
+
+Mount options:
+
+| Option | Required | Meaning |
+| --- | --- | --- |
+| `at` | yes | HTTP mount prefix. |
+| `accessTokens` | yes | One or more non-empty backend-held bearer tokens. |
+| `projects` | yes | Explicit project/stage allowlist with absolute Rampway config paths and approved release branches. |
+| `databaseIdentifier` | no | Velocious database used for runs/audits; default `default`. |
+| `staleRunTimeoutMs` | no | Ownership lease; default `60000`, minimum `4`. |
+
+## Client calls
+
+Create a run from a client whose token is also loaded from explicit backend
+secrets (not an environment fallback or command argument):
+
+```js
+import deploymentClientSecrets from "./config/secrets/deployment-client.js"
+
+const baseUrl = "https://app.example/rampway/deployments"
+const headers = {
+  Authorization: `Bearer ${deploymentClientSecrets.rampwayAccessToken}`,
+  "Content-Type": "application/json"
+}
+const createResponse = await fetch(`${baseUrl}/runs`, {
+  method: "POST",
+  headers,
+  body: JSON.stringify({
+    project: "my-app",
+    stage: "production",
+    revision: "0123456789abcdef0123456789abcdef01234567",
+    idempotencyKey: "release-2026-08-03-1"
+  })
+})
+const created = await createResponse.json()
+```
+
+Read the durable result:
+
+```js
+const runResponse = await fetch(`${baseUrl}/runs/${encodeURIComponent(created.run.id)}`, {headers})
+const {run, current} = await runResponse.json()
+```
+
+Authentication is accepted only from the `Authorization` header. Never place
+the token in a URL or command argument that is logged; clients should obtain it
+from their own secret store and configure the HTTP library's header directly.
+Rampway never includes tokens in response data, run state, audit payloads, Git
+commands, deploy commands, or deployment reports. Adapter values and object
+keys are JSON-normalized and recursively redacted before persistence. Sanitized
+structures are limited to 100 entries per array/object, 1,000 visited values,
+20 levels, 4,000 characters per string, and 64 KiB total serialized output;
+explicit truncation markers and a bounded redacted preview retain diagnostic
+context.
+
+Create responses are bounded:
+
+- `202`: created; execution continues in a fresh Velocious connection context.
+- `200`: matching idempotent replay; the original run is returned.
+- `401`: missing or invalid bearer token.
+- `404`: project/stage is not allowlisted.
+- `409`: key conflict, an active deployment, or operator reconciliation is required.
+- `422`: invalid request parameters.
+
+Run status is one of `pending`, `running`, `succeeded`, `failed`, `interrupted`,
+or `reconciliation_required`. Failed runs include sanitized recovery state.
+An immutable revision that is not reachable from the approved branch is
+recorded as a sanitized failed run rather than discarded before admission.
+Readback also reports the current/previous Rampway release and active revision.
+If live status cannot be read, the response still returns the durable run with
+`live_status: null` and a sanitized `live_status_error` annotation; the outage
+is also sent to Velocious framework error reporting.
+
+## Execution and recovery guarantees
+
+Rampway serializes durable admission before validating reachability on the
+deployment target, so an idempotent retry storm performs the Git fetch only for
+the created run. It then invokes the same `deploy()` used by the CLI: deploy
+lock, immutable remote-Git release, linked state, build/migration tasks, runtime
+handoff, health checks, `current` link, cleanup, and report persistence. It does
+not implement an alternate deployment engine or arbitrary command bridge. If
+failure occurs after the requested revision becomes active, the executor calls
+Rampway's existing rollback lifecycle with the captured prior current release
+as its explicit target and records whether that previous live state was
+restored.
+
+Runs and audits are stored in `rampway_deployment_runs` and
+`rampway_deployment_api_audit_events`, scoped by a stable hash of the mount.
+Target and idempotency advisory locks prevent duplicate concurrent admission,
+including one key racing across targets. Pending/running/terminal transitions
+are fenced by mount, run, owner, status, and (for stale reconciliation) the
+observed heartbeat. A renewed live owner therefore cannot be reclaimed, and an
+expired owner cannot overwrite a reconciled run.
+
+Pending work whose lease expires becomes `interrupted` and no longer blocks a
+new run. A stale running run, or a known successful activation whose success
+record could not be persisted, becomes `reconciliation_required` and continues
+to block duplicates until an operator verifies live state. Audit persistence
+failure is reported through both Velocious `framework-error` and `all-error`
+events and never strands deployment execution.
+Keyed retries and run-status polling evaluate the lease before returning, so a
+dead owner's stale `pending` or `running` state is reconciled without requiring
+a different-key deployment attempt.
+
+## Token rotation and revocation
+
+Use overlapping tokens for zero-downtime rotation:
+
+1. Add a new random token to the backend secrets list and restart/deploy every
+   web worker.
+2. Move every authorized client to the new token.
+3. Remove the old token from backend secrets and restart/deploy every worker
+   again.
+4. Confirm the old token receives `401` on every instance.
+
+For emergency revocation, remove the compromised token and restart all workers
+immediately. Revocation affects new HTTP requests; an already authenticated,
+durably admitted run continues under its owner lease. Inspect the run and audit
+records, reconcile any ambiguous running result, and rotate any repository or
+host credentials independently if they may also be compromised.
+
+Do not print tokens while diagnosing authentication. Record only token version
+or fingerprint metadata in an external secret inventory, never the token
+itself. Rampway framework-error payloads deliberately omit the HTTP request so
+listeners cannot accidentally serialize its Authorization header.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rampway",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "JS-native Capistrano-style release-directory deployments with Rollbridge integration.",
   "type": "module",
   "private": false,
@@ -54,6 +54,14 @@
       "types": "./build/src/test-helpers.d.ts",
       "default": "./build/src/test-helpers.js"
     },
+    "./velocious": {
+      "types": "./build/src/velocious/index.d.ts",
+      "default": "./build/src/velocious/index.js"
+    },
+    "./velocious.js": {
+      "types": "./build/src/velocious/index.d.ts",
+      "default": "./build/src/velocious/index.js"
+    },
     "./package.json": "./package.json"
   },
   "imports": {
@@ -64,8 +72,10 @@
   },
   "scripts": {
     "test": "npm run build && node --test tests/**/*.test.js",
-    "lint": "eslint src/ tests/",
+    "lint": "eslint src/ tests/ scripts/",
     "typecheck": "tsc --noEmit",
+    "verify:docker-dev-environment": "node scripts/verify-docker-dev-environment.js",
+    "test:docker-dev-environment": "node --test tests/docker-dev-environment.test.js",
     "clean": "node scripts/clean.js",
     "compile": "tsc -b",
     "postcompile": "node scripts/ensure-cli-executable.js",
@@ -84,7 +94,16 @@
   "devDependencies": {
     "eslint": "^9.39.2",
     "eslint-plugin-jsdoc": "^61.5.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "velocious": "^1.0.574"
+  },
+  "peerDependencies": {
+    "velocious": "^1.0.574"
+  },
+  "peerDependenciesMeta": {
+    "velocious": {
+      "optional": true
+    }
   },
   "files": [
     "build",