@onvoi/app-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onvoi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @onvoi/app-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional helpers for apps hosted on Onvoi. Nothing here is required — every
+call wraps a documented HTTP contract, so any JWT library and `fetch` work too.
+Zero dependencies; Node 18+.
+
+```js
+const { onvoi } = require('@onvoi/app-sdk');
+
+// Who is signed in (verifies X-Onvoi-Identity against Onvoi's published keys)
+const me = await onvoi.identity.verify(req);          // Express req, Lambda event, or the raw header
+
+// Your app's database, with that person's permissions
+const items = onvoi.data.collection('items');
+await items.find({ sku: 'A1' }, { as: me });
+await items.create({ sku: 'B2', qty: 3 }, { as: me });
+
+// Files (needs services.objectStorage.provision: true in onvoi.yaml)
+const file = await onvoi.files.upload('receipt.pdf', pdfBuffer, { contentType: 'application/pdf', as: me });
+const { url } = await onvoi.files.get(file.id, { as: me });   // short-lived download link
+
+// Events from your app's catalog, and approved actions of other apps
+await onvoi.events.publish('inventory.stock.low', { sku: 'A1' }, { idempotencyKey: 'A1-2026-10-24' });
+await onvoi.apps.call('crm', 'crm.contacts.lookup', { email: 'a@b.co' }, { as: me });
+// Retrying a write? Reuse the same idempotencyKey and it runs only once:
+await onvoi.apps.call('crm', 'crm.contacts.create', { email: 'a@b.co' }, { as: me, idempotencyKey: 'signup-123' });
+// Containers: keep the platform token fresh, and answer health checks
+app.use(onvoi.middleware());
+onvoi.health.express(app);                            // GET /healthz → 200 (set runtime.health.path)
+```
+
+The platform sets everything it needs in the environment: `ONVOI_ENV_ID`,
+`ONVOI_OIDC_ISSUER`, `ONVOI_JWKS_URL`, `ONVOI_DATA_API_URL`,
+`ONVOI_PLATFORM_URL` and `ONVOI_WORKLOAD_TOKEN` (refreshed on every request).
+
+MIT licensed.

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@onvoi/app-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Optional helpers for apps hosted on Onvoi: verify the signed-in person, use the app's database, publish events, call other apps.",
+  "license": "MIT",
+  "main": "src/index.js",
+  "files": ["src", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node --test test/*.test.js" },
+  "keywords": ["onvoi", "sdk"]
+}

package/src/index.js

@@ -0,0 +1,210 @@
+/**
+ * @onvoi/app-sdk — optional helpers for apps hosted on Onvoi (spec-03 §4).
+ *
+ * Nothing here is required: every call is a thin wrapper over the documented
+ * HTTP contracts, and an app can use any JWT library and plain fetch instead.
+ * Zero dependencies (Node ≥ 18: global fetch + node:crypto).
+ *
+ *   const { onvoi } = require('@onvoi/app-sdk');
+ *   const me = await onvoi.identity.verify(req);             // the signed-in person
+ *   const items = onvoi.data.collection('items');
+ *   await items.find({ sku: 'A1' }, { as: me });             // access rules evaluated as them
+ *   await onvoi.events.publish('inventory.stock.low', { sku: 'A1' });
+ *   await onvoi.apps.call('crm', 'crm.contacts.lookup', { email }, { as: me });
+ *   onvoi.health.express(app);                               // GET /healthz → 200
+ *
+ * Environment (set by the platform): ONVOI_ENV_ID, ONVOI_OIDC_ISSUER,
+ * ONVOI_JWKS_URL, ONVOI_DATA_API_URL (or ONVOI_PUBLIC_ORIGIN),
+ * ONVOI_PLATFORM_URL, ONVOI_WORKLOAD_TOKEN (refreshed on every request).
+ */
+const crypto = require('crypto');
+
+class OnvoiError extends Error {
+  constructor(status, code, message, details) {
+    super(message || code || `HTTP ${status}`);
+    this.name = 'OnvoiError';
+    this.status = status;
+    this.code = code || 'error';
+    if (details) this.details = details;
+  }
+}
+
+function b64urlJson(part) {
+  return JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+}
+
+function headerOf(src, name) {
+  if (!src) return null;
+  if (typeof src === 'string') return src;
+  const h = src.headers || {};
+  if (typeof h.get === 'function') return h.get(name);
+  return h[name] || h[name.toLowerCase()] || null;
+}
+
+function createOnvoi(opts = {}) {
+  const env = opts.env || process.env;
+  const fetchImpl = opts.fetch || globalThis.fetch;
+  const now = opts.now || (() => Date.now());
+  let latestWorkload = null;
+  const jwks = { keys: null, at: 0 };
+
+  const cfg = () => ({
+    envId: env.ONVOI_ENV_ID,
+    issuer: env.ONVOI_OIDC_ISSUER,
+    jwksUrl: env.ONVOI_JWKS_URL || (env.ONVOI_OIDC_ISSUER ? `${env.ONVOI_OIDC_ISSUER}/jwks.json` : null),
+    dataUrl: env.ONVOI_DATA_API_URL || (env.ONVOI_PUBLIC_ORIGIN ? `${env.ONVOI_PUBLIC_ORIGIN}/api/data` : null),
+    platformUrl: env.ONVOI_PLATFORM_URL,
+  });
+
+  async function request(url, { method = 'GET', headers = {}, body } = {}) {
+    if (!fetchImpl) throw new OnvoiError(0, 'no_fetch', 'fetch is not available (Node 18+ required)');
+    const r = await fetchImpl(url, { method, headers: { accept: 'application/json', ...(body !== undefined ? { 'content-type': 'application/json' } : {}), ...headers }, body: body !== undefined ? JSON.stringify(body) : undefined });
+    const text = await r.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { data = text; }
+    if (!r.ok) {
+      const e = (data && data.error) || {};
+      throw new OnvoiError(r.status, e.code, e.message || `HTTP ${r.status}`, e.details);
+    }
+    return data;
+  }
+
+  /* ── identity ─────────────────────────────────────────────────────── */
+  async function loadKeys(force = false) {
+    if (!force && jwks.keys && now() - jwks.at < 10 * 60 * 1000) return jwks.keys;
+    const { jwksUrl } = cfg();
+    if (!jwksUrl) throw new OnvoiError(0, 'not_configured', 'ONVOI_JWKS_URL is not set');
+    const doc = await request(jwksUrl);
+    jwks.keys = (doc && doc.keys) || [];
+    jwks.at = now();
+    return jwks.keys;
+  }
+
+  /**
+   * Verify an X-Onvoi-Identity assertion (a string, a Node/Express request, a
+   * Lambda event, or a fetch Request). Resolves to its claims; `claims.token`
+   * (non-enumerable) is the raw assertion, used by `{ as }` options.
+   */
+  async function verify(src, { audience } = {}) {
+    const token = headerOf(src, 'x-onvoi-identity');
+    if (!token) throw new OnvoiError(401, 'no_identity', 'No X-Onvoi-Identity on this request');
+    const parts = String(token).split('.');
+    if (parts.length !== 3) throw new OnvoiError(401, 'identity_invalid', 'Malformed identity assertion');
+    const head = b64urlJson(parts[0]);
+    const claims = b64urlJson(parts[1]);
+    if (head.alg !== 'RS256') throw new OnvoiError(401, 'identity_invalid', 'Unexpected algorithm');
+    let keys = await loadKeys();
+    let jwk = keys.find((k) => k.kid === head.kid);
+    if (!jwk) { keys = await loadKeys(true); jwk = keys.find((k) => k.kid === head.kid); }
+    if (!jwk) throw new OnvoiError(401, 'identity_invalid', 'Unknown signing key');
+    const pub = crypto.createPublicKey({ key: { kty: jwk.kty, n: jwk.n, e: jwk.e }, format: 'jwk' });
+    const ok = crypto.verify('RSA-SHA256', Buffer.from(`${parts[0]}.${parts[1]}`), pub, Buffer.from(parts[2], 'base64url'));
+    if (!ok) throw new OnvoiError(401, 'identity_invalid', 'Bad signature');
+    const { issuer, envId } = cfg();
+    const aud = audience || envId;
+    const t = Math.floor(now() / 1000);
+    if (issuer && claims.iss !== issuer) throw new OnvoiError(401, 'identity_invalid', 'Wrong issuer');
+    if (aud && !(Array.isArray(claims.aud) ? claims.aud.includes(String(aud)) : claims.aud === String(aud))) throw new OnvoiError(401, 'identity_invalid', 'Assertion is for a different app environment');
+    if (typeof claims.exp === 'number' && claims.exp + 5 < t) throw new OnvoiError(401, 'identity_expired', 'Identity assertion expired');
+    if (typeof claims.nbf === 'number' && claims.nbf - 5 > t) throw new OnvoiError(401, 'identity_invalid', 'Identity assertion not yet valid');
+    Object.defineProperty(claims, 'token', { value: token, enumerable: false });
+    return claims;
+  }
+
+  const asHeader = (as) => {
+    const tok = !as ? null : typeof as === 'string' ? as : as.token || headerOf(as, 'x-onvoi-identity');
+    if (!tok) throw new OnvoiError(400, 'as_required', 'Pass { as: <verified identity> } so the call runs with that person\'s permissions');
+    return { 'x-onvoi-identity-forward': tok };
+  };
+
+  /* ── data ─────────────────────────────────────────────────────────── */
+  function collection(name) {
+    const base = () => {
+      const { dataUrl } = cfg();
+      if (!dataUrl) throw new OnvoiError(0, 'not_configured', 'ONVOI_DATA_API_URL is not set');
+      return `${dataUrl.replace(/\/+$/, '')}/${encodeURIComponent(name)}`;
+    };
+    return {
+      find: (filter = {}, { as, sort, limit, cursor } = {}) => request(`${base()}/query`, { method: 'POST', headers: asHeader(as), body: { filter, ...(sort ? { sort } : {}), ...(limit ? { limit } : {}), ...(cursor ? { cursor } : {}) } }),
+      get: (id, { as } = {}) => request(`${base()}/${encodeURIComponent(id)}`, { headers: asHeader(as) }),
+      create: (doc, { as } = {}) => request(base(), { method: 'POST', headers: asHeader(as), body: doc }),
+      update: (id, patch, { as, ifMatch } = {}) => request(`${base()}/${encodeURIComponent(id)}`, { method: 'PATCH', headers: { ...asHeader(as), ...(ifMatch ? { 'if-match': String(ifMatch) } : {}) }, body: patch }),
+      remove: (id, { as } = {}) => request(`${base()}/${encodeURIComponent(id)}`, { method: 'DELETE', headers: asHeader(as) }),
+    };
+  }
+
+  /* ── files (services.objectStorage) ───────────────────────────────── */
+  const filesBase = () => {
+    const { dataUrl } = cfg();
+    if (!dataUrl) throw new OnvoiError(0, 'not_configured', 'ONVOI_DATA_API_URL is not set');
+    return `${dataUrl.replace(/\/+$/, '')}/_files`;
+  };
+  const files = {
+    /** Upload bytes (Buffer/Uint8Array/string): reserve → PUT → confirm. */
+    async upload(name, bytes, { contentType = 'application/octet-stream', as } = {}) {
+      const body = typeof bytes === 'string' ? Buffer.from(bytes) : bytes;
+      const start = await request(filesBase(), { method: 'POST', headers: asHeader(as), body: { name, contentType, size: body.length } });
+      // Development stores bytes through the Data API itself; production
+      // hands out a presigned storage URL (no Onvoi headers there).
+      const viaDataApi = /\/_files\/[^/]+\/content$/.test(new URL(start.upload.url).pathname);
+      const r = await fetchImpl(start.upload.url, { method: 'PUT', headers: { ...start.upload.headers, ...(viaDataApi ? asHeader(as) : {}) }, body });
+      if (!r.ok) throw new OnvoiError(r.status, 'upload_failed', `Upload failed (HTTP ${r.status})`);
+      return viaDataApi ? r.json() : request(`${filesBase()}/${start.file.id}/complete`, { method: 'POST', headers: asHeader(as), body: {} });
+    },
+    list: ({ as, limit, cursor } = {}) => request(`${filesBase()}?${new URLSearchParams({ ...(limit ? { limit: String(limit) } : {}), ...(cursor ? { cursor } : {}) })}`, { headers: asHeader(as) }),
+    /** Details plus a short-lived download URL. */
+    get: (id, { as } = {}) => request(`${filesBase()}/${encodeURIComponent(id)}`, { headers: asHeader(as) }),
+    remove: (id, { as } = {}) => request(`${filesBase()}/${encodeURIComponent(id)}`, { method: 'DELETE', headers: asHeader(as) }),
+  };
+
+  /* ── platform (events, app-to-app) ────────────────────────────────── */
+  function workloadToken() {
+    const t = latestWorkload || env.ONVOI_WORKLOAD_TOKEN;
+    if (!t) throw new OnvoiError(0, 'not_configured', 'ONVOI_WORKLOAD_TOKEN is not set');
+    return t;
+  }
+  function platform(path, body, headers = {}) {
+    const { platformUrl } = cfg();
+    if (!platformUrl) throw new OnvoiError(0, 'not_configured', 'ONVOI_PLATFORM_URL is not set');
+    return request(`${platformUrl.replace(/\/+$/, '')}${path}`, { method: 'POST', headers: { authorization: `Bearer ${workloadToken()}`, ...headers }, body });
+  }
+
+  const events = {
+    /** Publish an event from this app's catalog. `id` defaults to idempotencyKey or a random id. */
+    publish: (type, data = {}, { id, idempotencyKey, correlationId, version } = {}) => platform('/events', {
+      id: id || idempotencyKey || crypto.randomUUID(), type, data, ...(version ? { version } : {}), ...(correlationId ? { correlationId } : {}),
+    }),
+  };
+
+  const apps = {
+    /** Call another app's approved action. `{ as }` acts for that person; without it, as this app. */
+    call: async (slug, capability, input = {}, { as, correlationId, idempotencyKey } = {}) => {
+      const headers = { ...(as ? asHeader(as) : {}), ...(correlationId ? { 'x-onvoi-correlation-id': correlationId } : {}), ...(idempotencyKey ? { 'idempotency-key': String(idempotencyKey) } : {}) };
+      const r = await platform(`/apps/${encodeURIComponent(slug)}/capabilities/${encodeURIComponent(capability)}`, input, headers);
+      return r && Object.prototype.hasOwnProperty.call(r, 'result') ? r.result : r;
+    },
+  };
+
+  /* ── server helpers ───────────────────────────────────────────────── */
+  /** Remember the fresh workload token Onvoi attaches to each request (containers). */
+  function capture(src) {
+    const t = headerOf(src, 'x-onvoi-workload-token');
+    if (t) latestWorkload = t;
+    return t;
+  }
+  /** Express/Connect middleware: keeps the workload token fresh. */
+  function middleware() {
+    return (req, res, next) => { capture(req); next(); };
+  }
+  const health = {
+    express: (app, { path = '/healthz' } = {}) => {
+      app.get(path, (req, res) => res.status(200).json({ ok: true }));
+      return app;
+    },
+  };
+
+  return { identity: { verify }, data: { collection }, files, events, apps, health, middleware, capture, OnvoiError, _loadKeys: loadKeys };
+}
+
+const onvoi = createOnvoi();
+module.exports = { onvoi, createOnvoi, OnvoiError };