@vekil/app-sdk 0.4.0

package/docs/security-and-versioning.md

@@ -0,0 +1,147 @@
+# Security and versioning
+
+Remote Apps execute in developer-operated infrastructure. This guide describes
+the security responsibilities that apply before an App handles real requests.
+
+## Responsibility boundary
+
+| Area          | Vekil provides                                              | Your Runtime provides                                        |
+| ------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
+| Authorization | Signed, scoped, expiring installation and execution grants. | Provider authorization attempts and encrypted token storage. |
+| Execution     | Approved action, retry, timeout, and cancellation metadata. | Strict validation, provider calls, and idempotent effects.   |
+| Context       | The minimum declared context for the current action.        | Use only supplied fields for the duration of the request.    |
+| Credentials   | Request-signing verification material.                      | Runtime signing key and all provider credentials.            |
+| Results       | Validation and requester-facing conversation.               | Typed outcomes, facts, artifacts, and safe Bubbles.          |
+
+A Remote App must not call another App directly. Return typed artifacts when a
+later action may need structured data; Vekil handles authorized composition.
+
+## Signed requests and responses
+
+`createRemoteAppRuntime` verifies requests before handler dispatch:
+
+- Ed25519 signature and key selection;
+- issuer and audience;
+- timestamp and signature lifetime;
+- one-time nonce through the replay store;
+- exact raw-body digest;
+- request schema;
+- compatibility with the loaded Runtime manifest.
+
+Responses are signed with the Runtime key and verified by Vekil against the
+public JWKS declared by the App.
+
+Do not terminate signature verification in a generic reverse proxy unless the
+verified sender and exact raw body remain cryptographically bound to the
+Runtime process. The SDK adapters are the supported verification boundary.
+
+## Secrets
+
+Never place these values in an App Definition, manifest, App Context, Bubble,
+artifact, log, or source repository:
+
+- Runtime signing private JWK;
+- provider OAuth client secret;
+- provider access or refresh token;
+- API key or webhook secret;
+- database or vault encryption key;
+- credentials received from Vekil.
+
+The public JWKS contains public signing material only. Keep provider account
+references and raw provider payloads in the Runtime when they are needed; send
+Vekil only the declared normalized result.
+
+## Replay protection and idempotency
+
+These controls solve different problems and both are required:
+
+- The replay store atomically claims each signed request nonce until it expires.
+- Business idempotency stores the durable result for the supplied idempotency
+  key and returns the same result for duplicate delivery.
+
+A request may be retried with a new signature and nonce while retaining the
+same business idempotency key.
+
+## Validate every boundary
+
+The SDK validates protocol envelopes. Your App validates provider and business
+data:
+
+- parse App-owned action input before using it;
+- read reserved artifacts through SDK helpers;
+- resolve local action and outcome keys through manifest bindings;
+- treat provider responses, webhooks, redirects, and requester strings as
+  untrusted;
+- normalize provider errors without leaking payloads or credentials;
+- return only outcomes and artifacts declared by the App;
+- expose requester-visible results only when independently safe.
+
+## Provider authorization
+
+Use a high-entropy, one-time state value for every provider authorization
+attempt. Bind it to the installation, expected callback, requested permissions,
+and expiry. Consume it atomically.
+
+After callback:
+
+- verify state before exchanging a code;
+- compare the granted permissions with the requested contract;
+- encrypt tokens at rest;
+- rotate refresh credentials safely;
+- revoke credentials on disconnect;
+- reject a callback for an older or replaced connection attempt.
+
+Do not send provider tokens through App settings or App Context.
+
+## SDK and App updates
+
+The SDK package and the App released through Builder have separate lifecycles.
+Updating `@vekil/app-sdk` in source code does not change an installed App.
+
+To ship an SDK update in an App:
+
+1. update and lock the dependency;
+2. run validation, conformance, and tests;
+3. rebuild `definition.json`;
+4. prepare a new test release in Builder;
+5. download its manifest and deploy the matching Runtime;
+6. run the Runtime test;
+7. release the tested result and upgrade installations explicitly.
+
+## Compatibility before 1.0
+
+The SDK follows Semantic Versioning with a pre-1.0 policy:
+
+- patch releases (`0.4.x`) preserve public API and protocol behavior for that
+  minor line, except when a fail-closed security correction is required;
+- minor releases (`0.x.0`) may contain author-facing breaking changes and must
+  include migration guidance;
+- published package versions are immutable;
+- the current minor line is the actively supported development line.
+
+Use `^0.4.0` to receive compatible `0.4.x` patches without crossing into
+`0.5.0`. Commit the package-manager lockfile for reproducible builds.
+
+## Deprecation
+
+Deprecated exports remain documented for the supported minor line when a safe
+migration exists. Security-sensitive behavior may fail closed immediately when
+continuing it would expose credentials, widen authority, accept replay, or
+execute an undeclared side effect.
+
+Compatibility aliases are not added for retired fields, routes, or enum values.
+
+## Report a vulnerability
+
+Do not open a public issue containing credentials, personal data, or a working
+exploit against a deployed Runtime. Contact Vekil privately through the security
+contact published on [vekil.me](https://vekil.me) and include:
+
+- affected SDK and App versions;
+- the impacted boundary;
+- minimal reproduction steps;
+- expected and observed behavior;
+- whether credentials or user data may have been exposed.
+
+Public product bugs and documentation issues may be reported in the repository
+issue tracker linked by the package metadata.

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@vekil/app-sdk",
+  "version": "0.4.0",
+  "description": "Build, validate, test, and host Remote Apps for Vekil.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Vekil",
+    "url": "https://vekil.me"
+  },
+  "homepage": "https://vekil.me/docs/remote",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/askvekil/vekil.me.git",
+    "directory": "packages/platform/app-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/askvekil/vekil.me/issues"
+  },
+  "keywords": [
+    "vekil",
+    "app-sdk",
+    "remote-apps",
+    "typescript",
+    "automation"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "bin": {
+    "vekil-app": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./runtime": {
+      "import": {
+        "types": "./dist/runtime.d.ts",
+        "default": "./dist/runtime.js"
+      },
+      "require": {
+        "types": "./dist/runtime.d.cts",
+        "default": "./dist/runtime.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint .",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@types/node": "26.1.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@vekil/app-compiler": "workspace:*",
+    "@vekil/app-protocol": "workspace:*",
+    "@vekil/app-runtime": "workspace:*",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
+  }
+}