@vekil/app-sdk 0.4.0

package/docs/app-definition.md

@@ -0,0 +1,223 @@
+# App Definition
+
+An App Definition describes what a Remote App offers, when it should be used,
+which information it needs, and what results it can return.
+
+Use the exported TypeScript types while authoring. Use `vekil-app schema` when
+an editor or another tool needs JSON Schema. Both represent the same strict
+contract.
+
+## Choose a starting point
+
+`createRemoteAppStarterDefinition` creates a minimal read-only App with one
+intent, capability, action, and outcome. It is useful for validating a new
+Runtime and learning the release workflow.
+
+`defineRemoteApp` accepts the complete `AppDefinitionInput`:
+
+```ts
+import { defineRemoteApp, type AppDefinitionInput } from "@vekil/app-sdk";
+
+const input = {
+  // Complete strict Definition.
+} satisfies AppDefinitionInput;
+
+export default defineRemoteApp(input);
+```
+
+Unknown fields are rejected. Defaults are normalized during parsing, so build
+and import the value returned by `defineRemoteApp`.
+
+## Top-level structure
+
+| Field               | Purpose                                                                 |
+| ------------------- | ----------------------------------------------------------------------- |
+| `definitionVersion` | Selects the supported Definition contract.                              |
+| `defaultLocale`     | Fallback locale for App-owned copy.                                     |
+| `app`               | Listing name, descriptions, category, optional icon, and provider name. |
+| `publication`       | Optional website, support email, privacy policy, and terms.             |
+| `connection`        | Explains account connection and requested provider permissions.         |
+| `intents`           | Requests the App understands and the information each request needs.    |
+| `capabilities`      | User-visible abilities backed by one or more actions.                   |
+| `actions`           | Typed operations the Runtime can plan and execute.                      |
+| `outcomes`          | Typed results and allowed continuations.                                |
+| `artifactContracts` | Versioned data passed between planned actions.                          |
+| `settings`          | Values configured separately by each installer.                         |
+| `policies`          | Installer-controlled approval behavior.                                 |
+| `knowledge`         | Installed information available for answering and planning.             |
+| `context`           | Requested App Context scopes and their disclosure copy.                 |
+| `publicActions`     | Safe quick starts shown on a public Vekil page.                         |
+| `customRules`       | App-specific rule families and examples.                                |
+| `runtime`           | Runtime base URL, JWKS URL, and connection requirement.                 |
+
+The generated schema contains every field constraint:
+
+```bash
+vekil-app schema ./app-definition.schema.json
+```
+
+## Local keys
+
+Use stable local keys such as `find-options`, `create-record`, and
+`record-created` to connect Definition entries.
+
+Good keys are:
+
+- lowercase kebab-case;
+- descriptive of behavior rather than UI copy;
+- stable when labels or descriptions change;
+- unique within their collection.
+
+The Runtime resolves these keys with `createAppRuntimeBindings`. Business code
+should not construct runtime references by concatenating strings.
+
+## Localized copy
+
+App-specific interface copy belongs in the Definition:
+
+```ts
+const title = {
+  en: "Find available options",
+  fr: "Trouver des options disponibles"
+};
+```
+
+Use valid locale codes as keys. Every required localized field must include the
+`defaultLocale`. Translate meaning, while keeping keys and schemas stable.
+
+## Intents, capabilities, actions, and outcomes
+
+These layers answer different questions:
+
+| Layer      | Question                                      |
+| ---------- | --------------------------------------------- |
+| Intent     | What is the requester trying to accomplish?   |
+| Capability | What useful ability does the App provide?     |
+| Action     | What typed operation can the Runtime perform? |
+| Outcome    | What happened, and may the request continue?  |
+
+### Intents
+
+An intent declares:
+
+- positive and negative examples;
+- required and optional fields;
+- questions for missing information;
+- supported conversation origins;
+- related capabilities and actions;
+- risk and requester-review behavior;
+- response guidance.
+
+Examples teach recognition. They are not scripted replies and requesters do not
+need to repeat them exactly.
+
+Choose the intent mode by outcome:
+
+- `ANSWER` returns information without creating a submission;
+- `COLLECT` gathers a complete structured request;
+- `EXECUTE` plans and performs a Runtime action.
+
+### Capabilities
+
+A capability is the installer-visible promise made by the App. Group actions
+only when they form one coherent ability, and describe the result in ordinary
+language.
+
+### Actions
+
+An action owns:
+
+- input and output JSON Schema;
+- side-effect and risk level;
+- approval behavior;
+- required settings, policies, and context;
+- timeout, retry, and idempotency rules;
+- possible outcomes and artifacts.
+
+Use the narrowest input and context needed. A read-only planning operation must
+not perform a write.
+
+### Outcomes
+
+An outcome represents a typed result. Add a continuation only when the same
+request genuinely remains open, such as after presenting a bounded choice of
+available options.
+
+## Settings and policies
+
+Settings are configured separately for every installation. The same App can
+therefore serve different people or organizations without separate releases.
+
+Common settings include:
+
+- a selected workspace or calendar;
+- working days and hours;
+- a destination queue;
+- public information supplied by the installer.
+
+Policies control approval and supported behavior. They should be explicit
+installer choices rather than hidden prompt text.
+
+Do not put provider credentials in settings. OAuth clients, access tokens, API
+keys, and webhook secrets belong in the Remote Runtime's credential store.
+
+## App Context
+
+Each action requests the minimum context it needs. Context is scoped to one
+authorized operation and can be absent or expire.
+
+Treat optional context as unavailable when it is not supplied. Never infer
+permission from an undeclared field or ask for broad context as a convenience.
+
+## Artifacts
+
+Artifacts are typed values produced by one action and consumed by a later
+planned action. Declare:
+
+- a stable local key;
+- schema version and JSON Schema;
+- sensitivity level;
+- allowed audiences;
+- producer and consumer actions;
+- expected cardinality.
+
+Read action input and reserved artifacts separately:
+
+```ts
+import { readAppActionInput, readAppContextArtifactInputs } from "@vekil/app-sdk";
+
+const input = inputSchema.parse(readAppActionInput(request.input));
+const artifacts = readAppContextArtifactInputs(request.input);
+```
+
+Return requester-visible data only when it is safe independently of the chat
+copy around it.
+
+## Public actions
+
+Public actions become concise quick starts on a Vekil page. Each one must map
+to a declared intent and capability and accurately describe work the installed
+App can handle.
+
+Keep the list short and concrete. A quick start begins a conversation; normal
+clarification, verification, approval, and execution rules still apply.
+
+## Publication metadata
+
+Website, privacy policy, terms, and support email are optional. Add only links
+that are live and maintained. Developer name, handle, and social links come
+from the Builder profile and do not belong in the Definition.
+
+## Validate before import
+
+```bash
+vekil-app validate ./vekil.app.mjs
+vekil-app conformance ./vekil.app.mjs
+vekil-app build ./vekil.app.mjs --out ./dist
+```
+
+`validate` checks schema and semantic references. `conformance` adds Remote
+Runtime requirements. `build` writes canonical JSON and the matching schema.
+
+Import `dist/definition.json` into Builder. Builder performs the final test with
+the deployed Runtime before an App can be released.

package/docs/cli.md

@@ -0,0 +1,163 @@
+# CLI reference
+
+The `vekil-app` CLI creates and validates Remote App projects with the same
+contracts exported by the SDK.
+
+Run it through a project script or directly:
+
+```bash
+pnpm vekil-app help
+pnpm dlx @vekil/app-sdk help
+```
+
+Commands write normal results to standard output, validation issues to standard
+error, and return a non-zero exit code on failure.
+
+## `init`
+
+Create a fail-closed Remote App starter:
+
+```bash
+vekil-app init <directory> [--name <name>] [--runtime-url <url>]
+```
+
+- The target directory must be empty.
+- The default Runtime URL is `http://localhost:4100`.
+- Deployed URLs must use HTTPS; HTTP is accepted only on localhost.
+- The generated package is private and pins the current SDK minor line.
+- Planning and execution remain disabled until you implement the handlers.
+
+Example:
+
+```bash
+pnpm dlx @vekil/app-sdk init calendar-runtime \
+  --name "Calendar" \
+  --runtime-url http://localhost:4100
+```
+
+## `validate`
+
+Parse and validate a Definition:
+
+```bash
+vekil-app validate <definition.json|module.mjs>
+```
+
+JavaScript modules may export the Definition as `default` or as a named
+`definition` value. Validation rejects unknown fields, invalid schemas,
+duplicate local keys, broken references, unsafe context, and inconsistent
+approval or artifact contracts.
+
+## `conformance`
+
+Run Definition checks and require a Remote Runtime declaration:
+
+```bash
+vekil-app conformance <definition.json|module.mjs>
+```
+
+Current local checks cover:
+
+- strict Definition validity;
+- deterministic canonical JSON;
+- Remote Runtime requirements.
+
+Builder performs the deployed Runtime test separately. Local conformance is not
+a replacement for that test or for a security review.
+
+## `build`
+
+Write the files needed for Builder import:
+
+```bash
+vekil-app build <definition.json|module.mjs> [--out <directory>]
+```
+
+The default output directory is `dist`:
+
+```text
+dist/
+├── app-definition.schema.json
+└── definition.json
+```
+
+Import `definition.json` into a Remote App project. Do not hand-edit the built
+JSON; change the source Definition and rebuild it.
+
+## `inspect`
+
+Print a concise JSON summary:
+
+```bash
+vekil-app inspect <definition.json|module.mjs>
+```
+
+The output includes the public name, locale, category, connection type,
+capability keys, publication links, and Runtime endpoints. It is useful in CI
+and release reviews.
+
+## `schema`
+
+Print or write the App Definition JSON Schema:
+
+```bash
+vekil-app schema
+vekil-app schema ./app-definition.schema.json
+```
+
+Use the generated file for editors, CI validation, and tooling. Regenerate it
+after changing the SDK version.
+
+## `keys`
+
+Generate Runtime signing keys from the manifest downloaded from Builder:
+
+```bash
+vekil-app keys [manifest.json] [--key-id <key-id>]
+```
+
+The default path is `./vekil.manifest.json`.
+
+The command prints:
+
+- `VEKIL_APP_SIGNING_KEY_ID`;
+- `VEKIL_APP_SIGNING_PRIVATE_JWK_BASE64URL`;
+- the public JWKS document.
+
+Store the private values in a secret manager and publish only the JWKS.
+Redirecting command output to a committed file can leak the private key.
+
+## Generated project scripts
+
+The starter includes:
+
+```json
+{
+  "scripts": {
+    "build": "vekil-app build ./vekil.app.mjs --out ./dist",
+    "conformance": "vekil-app conformance ./vekil.app.mjs",
+    "dev": "node --env-file=.env runtime.mjs",
+    "keys": "vekil-app keys ./vekil.manifest.json",
+    "validate": "vekil-app validate ./vekil.app.mjs"
+  }
+}
+```
+
+Recommended CI sequence:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm validate
+pnpm conformance
+pnpm build
+git diff --exit-code -- dist/definition.json dist/app-definition.schema.json
+```
+
+Commit generated artifacts only when the App repository's release policy
+requires it. Always generate them with the SDK version locked by the project.
+
+## Operations handled in Builder
+
+The CLI does not sign in to Vekil, create or publish App releases, deploy Runtime
+code, or manage provider credentials. Use Builder for App testing and release;
+use your own deployment and secret-management systems for the Runtime.

package/docs/runtime.md

@@ -0,0 +1,256 @@
+# Remote Runtime
+
+A Remote Runtime is the HTTPS service that implements an App's typed actions.
+The SDK verifies incoming Vekil requests before your handlers run and signs the
+responses returned by those handlers.
+
+Your Runtime remains responsible for provider APIs, credentials, business
+rules, data storage, and operational reliability.
+
+## Recommended project structure
+
+```text
+src/
+├── actions/
+│   ├── execute.ts
+│   └── plan.ts
+├── connection/
+│   ├── complete.ts
+│   ├── disconnect.ts
+│   └── prepare.ts
+├── provider/
+│   ├── client.ts
+│   ├── mapper.ts
+│   └── token-vault.ts
+├── runtime/
+│   ├── bindings.ts
+│   ├── handlers.ts
+│   ├── replay-store.ts
+│   └── server.ts
+└── index.ts
+vekil.app.mjs
+vekil.manifest.json
+```
+
+Keep provider code separate from protocol adapters. Handlers should translate
+between typed App operations and provider-specific calls.
+
+## Runtime manifest
+
+Builder provides `vekil.manifest.json` when a test release is prepared. Keep
+that file with the matching Runtime deployment and load it at startup:
+
+```ts
+import manifest from "../vekil.manifest.json" with { type: "json" };
+import { createAppRuntimeBindings } from "@vekil/app-sdk/runtime";
+
+export const bindings = createAppRuntimeBindings(manifest);
+```
+
+The SDK validates the manifest and rejects local keys that are not part of the
+prepared release. Download a fresh manifest whenever the Definition changes.
+
+## Implement the handlers
+
+Provide all methods in `AppRuntimeV1Handlers`:
+
+| Handler                  | Responsibility                                                    |
+| ------------------------ | ----------------------------------------------------------------- |
+| `prepareInstallation`    | Start a connection flow or report that no connection is required. |
+| `completeInstallation`   | Verify the callback and return normalized connection status.      |
+| `disconnectInstallation` | Revoke provider access and App-owned connection state.            |
+| `planAction`             | Check feasibility and return bounded typed actions or questions.  |
+| `executeAction`          | Perform one approved action idempotently and return its result.   |
+| `health`                 | Report whether the current deployment can safely accept work.     |
+
+Protocol envelopes are validated only after signature, timestamp, audience,
+nonce, and schema checks pass. Your handlers must still validate App-owned
+fields before using them.
+
+Use enums exported by `@vekil/app-sdk` instead of free-form status strings.
+
+## Start the server
+
+```ts
+import { createRemoteAppRuntime } from "@vekil/app-sdk/runtime";
+
+const runtime = createRemoteAppRuntime({
+  handlers,
+  manifest,
+  platformJwksUrl: process.env.VEKIL_PLATFORM_JWKS_URL!,
+  replayStore,
+  signingIdentity
+});
+```
+
+For Fetch-compatible hosts:
+
+```ts
+export default {
+  fetch(request: Request): Promise<Response> {
+    return runtime.handle(request);
+  }
+};
+```
+
+For Node HTTP:
+
+```ts
+import { createServer } from "node:http";
+
+createServer((request, response) => {
+  void runtime.handleNodeRequest(request, response);
+}).listen(Number(process.env.PORT ?? 4100));
+```
+
+Both adapters preserve the signed raw body, reject bodies over 2 MiB, and serve
+the public JWKS endpoint declared by the App.
+
+## Generate signing keys
+
+Generate an Ed25519 key pair from the manifest downloaded from Builder:
+
+```bash
+pnpm vekil-app keys ./vekil.manifest.json
+```
+
+The command prints two private environment values and a public JWKS document.
+Store the private values in a secret manager. Publish only the JWKS.
+
+Load the private values without handling protocol issuers yourself:
+
+```ts
+import { readAppRuntimeSigningIdentity } from "@vekil/app-sdk/runtime";
+
+const signingIdentity = readAppRuntimeSigningIdentity({
+  manifest,
+  keyId: process.env.VEKIL_APP_SIGNING_KEY_ID,
+  privateJwkBase64url: process.env.VEKIL_APP_SIGNING_PRIVATE_JWK_BASE64URL
+});
+
+if (!signingIdentity) {
+  throw new Error("Runtime signing configuration is incomplete.");
+}
+```
+
+For rotation, publish both old and new public keys, deploy the new private key,
+wait through the accepted signature window, and then remove the old public key.
+Never expose a private JWK through the JWKS route.
+
+## Add replay protection
+
+Every production Runtime needs an atomic durable replay store:
+
+```ts
+import type { AppSignatureReplayClaim, AppSignatureReplayStore } from "@vekil/app-sdk/runtime";
+
+export class DurableReplayStore implements AppSignatureReplayStore {
+  async claim(input: AppSignatureReplayClaim): Promise<boolean> {
+    // Atomically claim this signed request until input.expiresAt.
+    // Return false if it was already claimed.
+    return true;
+  }
+}
+```
+
+Use a database uniqueness constraint or an atomic cache operation with expiry.
+A read followed by a separate write is unsafe under concurrency.
+
+`createDevelopmentReplayStore()` is process-local and exists only for local
+development and tests.
+
+## Connect provider accounts
+
+When an App needs OAuth or another provider login:
+
+1. `prepareInstallation` creates an authorization attempt bound to the signed
+   installation request and return URL.
+2. The user authorizes directly with the provider.
+3. The provider redirects to your Runtime callback.
+4. The Runtime verifies state, exchanges the code, and stores provider tokens
+   in its own encrypted credential store.
+5. `completeInstallation` consumes a one-time completion reference and returns
+   normalized connection status to Vekil.
+
+Provider client secrets, access tokens, refresh tokens, webhook secrets, and
+raw provider account payloads must never be returned to Vekil.
+
+Bind authorization attempts and stored credentials to the exact installation
+and current authorization grant. Reject stale callbacks, reused completion
+references, account switches, and permission downgrades.
+
+## Plan before executing
+
+`planAction` is read-only. It may:
+
+- validate provider reachability;
+- identify missing information;
+- return bounded choices;
+- propose declared actions;
+- provide typed grounding.
+
+It must not perform the requested side effect.
+
+`executeAction` receives one authorized action, App Context, idempotency key,
+and attempt number. It must:
+
+- validate App-owned input;
+- recheck provider preconditions immediately before a write;
+- use the supplied idempotency key for every side effect;
+- honor cancellation, timeout, and retry semantics;
+- return only declared outcomes, artifacts, and Bubbles;
+- classify retryable and non-retryable errors accurately.
+
+Return structured facts and results rather than an unbounded chat transcript.
+Vekil turns those results into a response and can continue the conversation.
+
+## Read App Context and artifacts
+
+App Context is scoped to one action and one authorization grant. Use only the
+scopes declared by that action. Treat a missing optional scope as unavailable.
+
+Reserved artifacts are available under `$artifacts`:
+
+```ts
+import { readAppActionInput, readAppContextArtifactInputs } from "@vekil/app-sdk";
+
+const input = inputSchema.parse(readAppActionInput(request.input));
+const artifacts = readAppContextArtifactInputs(request.input);
+```
+
+Consume only artifact contracts declared by the action. Preserve provenance and
+sensitivity, and never widen visibility in Runtime code.
+
+## Report health
+
+Use the SDK helper so the response always matches the loaded manifest:
+
+```ts
+import { AppRuntimeHealthStatus } from "@vekil/app-sdk";
+import { createAppRuntimeHealthResponse } from "@vekil/app-sdk/runtime";
+
+const health = async () =>
+  createAppRuntimeHealthResponse({
+    manifest,
+    status: AppRuntimeHealthStatus.HEALTHY
+  });
+```
+
+Return `HEALTHY` only when the deployment can safely accept all declared work.
+Use `DEGRADED` when the process is reachable but a required dependency or
+configuration is unavailable.
+
+## Production checklist
+
+- Deploy the Runtime and JWKS endpoints over HTTPS.
+- Deploy the exact manifest tested in Builder.
+- Store signing keys and provider credentials outside source control.
+- Use a durable atomic replay store with expiry.
+- Persist idempotency records and provider write results.
+- Keep outbound timeouts below the declared action timeout.
+- Redact credentials, signed bodies, personal data, and App Context from logs.
+- Emit request, execution, installation, and trace references safely.
+- Test duplicate delivery, retry, timeout, cancellation, and stale grants.
+- Test key rotation, token refresh, revocation, account switch, and scope change.
+- Keep database migrations and rollback behavior release-specific.
+- Run Builder's Runtime test before private installation or submission.