@sequenceholdings/managed-functions 0.1.1 → 0.2.0

package/README.md

@@ -1,15 +1,129 @@
 # `@sequenceholdings/managed-functions`
 
-`@sequenceholdings/managed-functions` is the TypeScript SDK for cache-enabled
-Managed Functions. Function code imports its context and cache types; Atlas and
-the local harness use its runtime helpers to construct the optional third
-handler argument. Ordinary two-argument handlers do not need this package.
+`@sequenceholdings/managed-functions` is the TypeScript SDK for Managed
+Functions. It provides caller-scoped ORM access and opt-in caching. The
+`/orm` import loads only the dependency-free ORM execution client, without
+initializing cache, storage, authentication or tracing libraries.
 
 Managed Functions is a workflow-agnostic platform primitive. The runtime owns
 generic invocation, isolation, secrets, egress, caching, and observability;
 deployed functions own business logic. Primitive code must not identify a
-function consumer or branch on a function ID. See
-[Platform primitive boundaries](../../../docs/platform/platform-primitives.md).
+function consumer or branch on a function ID.
+
+## ORM as the invoking user
+
+Available in SDK **0.2.0 and later**. Install the SDK in the function package;
+the separate ORM authoring/compiler package is not needed in the deployed
+function. Copy the namespace's generated `operations.manifest.json` into that
+package, and keep it synchronized with the applied namespace version.
+
+```ts
+import type { Request, Response } from '@google-cloud/functions-framework'
+import { createFunctionOrmExecutor, FunctionOrmError } from '@sequenceholdings/managed-functions/orm'
+import manifest from './operations.manifest.json'
+
+// Nonsecret configuration: use your deployment's URL, never request input.
+const platformOrigin = 'https://your-environment.example.com'
+
+export async function handler(request: Request, response: Response) {
+  try {
+    // Create inside every invocation; never keep this executor in module state.
+    const orm = createFunctionOrmExecutor({
+      request,
+      baseUrl: platformOrigin,
+      namespace: 'directory',
+      manifest,
+    })
+    const profile = await orm.execute('GetMyProfile', {})
+    response.json(profile)
+  } catch (error) {
+    if (error instanceof FunctionOrmError) {
+      response.status(403).json({ error: error.code })
+      return
+    }
+    // Do not expose arbitrary exceptions or upstream response bodies.
+    response.status(502).json({ error: 'PROFILE_UNAVAILABLE' })
+  }
+}
+```
+
+The manifest declares the account and data scope. Replace these illustrative
+names with your provisioned account, namespace, relations and mutation names:
+
+```yaml
+service_account: directory-runtime
+capabilities:
+  data:
+    directory:
+      tables: [my_profile]
+      operations: [UpdateMyProfile]
+      query: false
+```
+
+The deployer needs permission to bind the service account. The human caller
+needs function invocation access plus the namespace runtime grants and operation
+capabilities. `tables` covers read relations, including linked selections and
+policy dependencies; `operations` contains persisted mutation names. These
+declarations restrict access; they do not grant the caller access. Apply matching
+namespace operations before deploying consumers. Open the Managed Functions guide at `/docs/managed-functions/overview` on
+your administrator-supplied platform URL for provisioning, grants and deployment.
+
+`createFunctionOrmExecutor({ request, baseUrl, namespace, manifest, fetchImpl? })`
+returns an isolated executor with `execute(operationName, variables?)`. It sends
+only registered operation hashes and variables. The optional `fetchImpl` is for
+testing or an application-owned transport; it must honor `redirect: 'error'`.
+It never retries requests, follows redirects, reads credentials from a request
+body, substitutes a service token, or configures process-wide ORM state. Reuse
+within one handler invocation is supported; discard it when the handler returns.
+
+`baseUrl` must be an explicitly configured HTTPS origin, with no path, query,
+fragment or embedded credentials. Loopback HTTP is accepted for a local platform.
+There is no automatic environment URL: the helper never trusts a request header
+or body to choose where it sends a delegated credential.
+
+### Caller identity and trust boundary
+
+This helper supports direct human invocations through the platform gateway.
+Scheduled/system-runner and service-account invocations fail closed. They do not
+silently become an attached service account or a recorded human initiator.
+No Function UUID, profile lookup, signing key, bearer token or claims decoder is
+required in application code.
+
+The platform must control ingress to the deployed handler. The helper consumes
+the request delivered by that gateway; it does **not** authenticate arbitrary
+HTTP requests or make a publicly reachable Functions Framework server safe.
+Its local metadata checks only reject an unsupported or expired invocation mode.
+The ORM server verifies the credential's signature and expiry, checks its
+declared scope, resolves the caller's current permissions, and enforces row
+policies on every operation. The helper exposes no decoded caller identity or
+capabilities for use as a separate authorization decision.
+
+`seq-studio functions dev` does not mint delegated user identity. A missing
+context there is expected; validate pure handler logic with supplied test
+executors and verify real caller permissions through a deployed invocation.
+Do not copy real invocation headers into fixtures or logs.
+
+### Errors and recovery
+
+`FunctionOrmError.code` is stable and safe to return without including the
+exception's stack or request headers:
+
+| Code | Recovery |
+| --- | --- |
+| `INVALID_CONFIGURATION` | Correct the trusted origin or fetch configuration. |
+| `MISSING_CALLER_CONTEXT` | Declare the data binding and invoke through the platform as a signed-in user. |
+| `INVALID_CALLER_CONTEXT` | Verify that the request came through the supported platform runtime. |
+| `UNSUPPORTED_CALLER` | Use a direct human invocation; this helper has no service mode. |
+| `EXPIRED_CALLER_CONTEXT` | Begin a new invocation and construct a new executor. |
+
+Invalid manifests, unknown operations and ORM failures propagate `OrmClientError`
+or `OrmOperationError`, also exported from `/orm`. An `OrmOperationError` exposes
+`status` and `code`; handle those instead of returning its upstream message.
+A denied write is still denied; the helper supplies no permission
+fallback. A network error may follow a successful write: use application-level
+idempotency and inspect persisted results before retrying.
+
+## Opt-in cache
 
 Opt-in caching inside a Managed Function. When the manifest declares a `cache` block, the platform passes a process-reused `context` as the HTTP handler's third argument. Existing two-argument handlers keep working.
 

package/dist/orm.d.ts

@@ -0,0 +1,56 @@
+declare class OrmClientError extends Error {
+    readonly status: number | null;
+    readonly name: string;
+    constructor(message: string, status?: number | null);
+}
+interface OperationErrorEntry {
+    readonly message: string;
+    readonly extensions?: {
+        readonly code?: string;
+    };
+}
+declare class OrmOperationError extends OrmClientError {
+    readonly code: string | null;
+    readonly errors: readonly OperationErrorEntry[];
+    readonly name = "OrmOperationError";
+    constructor(message: string, status: number | null, code: string | null, errors?: readonly OperationErrorEntry[]);
+}
+
+/** One entry of `operations.manifest.json` (generated by `orm generate`). */
+interface ManifestOperation {
+    readonly hash: string;
+    readonly kind: 'query' | 'mutation';
+    readonly requires: {
+        readonly capability?: string;
+        readonly role?: string;
+    } | null;
+}
+interface OperationsManifest {
+    readonly schemaHash: string;
+    readonly opsHash?: string;
+    readonly operations: Readonly<Record<string, ManifestOperation>>;
+}
+interface OperationExecutor {
+    /** Execute a manifest operation by name (or a raw `sha256:` hash). */
+    execute<TData = Record<string, unknown>>(op: string, variables?: Record<string, unknown>): Promise<TData>;
+}
+
+type FunctionOrmErrorCode = 'INVALID_CONFIGURATION' | 'MISSING_CALLER_CONTEXT' | 'INVALID_CALLER_CONTEXT' | 'UNSUPPORTED_CALLER' | 'EXPIRED_CALLER_CONTEXT';
+declare class FunctionOrmError extends Error {
+    readonly code: FunctionOrmErrorCode;
+    readonly name = "FunctionOrmError";
+    constructor(code: FunctionOrmErrorCode, message: string);
+}
+interface FunctionOrmRequest {
+    readonly headers: Pick<Headers, 'get'> | Readonly<Record<string, string | readonly string[] | undefined>>;
+}
+interface FunctionOrmExecutorOptions {
+    request: FunctionOrmRequest;
+    baseUrl: string;
+    namespace: string;
+    manifest: unknown;
+    fetchImpl?: typeof globalThis.fetch;
+}
+declare function createFunctionOrmExecutor({ request, baseUrl, namespace, manifest, fetchImpl, }: FunctionOrmExecutorOptions): OperationExecutor;
+
+export { FunctionOrmError, type FunctionOrmErrorCode, type FunctionOrmExecutorOptions, type FunctionOrmRequest, type OperationExecutor, type OperationsManifest, OrmClientError, OrmOperationError, createFunctionOrmExecutor };

package/dist/orm.js

@@ -0,0 +1,224 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/orm.ts
+var orm_exports = {};
+__export(orm_exports, {
+  FunctionOrmError: () => FunctionOrmError,
+  OrmClientError: () => OrmClientError,
+  OrmOperationError: () => OrmOperationError,
+  createFunctionOrmExecutor: () => createFunctionOrmExecutor
+});
+module.exports = __toCommonJS(orm_exports);
+
+// ../orm/dist/client.js
+var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
+var ORM_DATA_TOKEN_HEADER = "x-sequence-data-token";
+var MATERIALIZE_ACTOR = "orm:materialize";
+JSON.stringify({ sub: MATERIALIZE_ACTOR, org: null, roles: [], capabilities: [] });
+var OrmClientError = class extends Error {
+  constructor(message, status = null) {
+    super(message);
+    this.status = status;
+  }
+  name = "OrmClientError";
+};
+var OrmOperationError = class extends OrmClientError {
+  constructor(message, status, code, errors = []) {
+    super(message, status);
+    this.code = code;
+    this.errors = errors;
+  }
+  name = "OrmOperationError";
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOperationError(value) {
+  if (!isRecord(value) || typeof value.message !== "string") return false;
+  if (value.extensions === void 0) return true;
+  return isRecord(value.extensions) && (value.extensions.code === void 0 || typeof value.extensions.code === "string");
+}
+function readOperationResponse({
+  ok,
+  status,
+  body
+}) {
+  const payload = isRecord(body) ? body : null;
+  const rawErrors = payload?.errors;
+  if (rawErrors !== void 0 && (!Array.isArray(rawErrors) || !rawErrors.every(isOperationError))) {
+    throw new OrmOperationError("malformed response: invalid errors", status, null);
+  }
+  const errors = rawErrors ?? [];
+  if (!ok || errors.length > 0) {
+    const first = errors[0];
+    throw new OrmOperationError(first?.message ?? `HTTP ${status}`, status, first?.extensions?.code ?? null, errors);
+  }
+  if (!payload || payload.data === void 0 || payload.data === null) {
+    throw new OrmOperationError("malformed response: missing data", status, null);
+  }
+  if (!isRecord(payload.data)) {
+    throw new OrmOperationError("malformed response: data must be an object", status, null);
+  }
+  return payload.data;
+}
+var operationHash = /^sha256:[a-f0-9]{64}$/;
+function readManifestHashes(manifest) {
+  if (!isRecord(manifest) || typeof manifest.schemaHash !== "string" || !manifest.schemaHash || !isRecord(manifest.operations)) {
+    throw new OrmClientError("invalid operations manifest \u2014 use operations.manifest.json from seq-studio orm generate");
+  }
+  const hashes = /* @__PURE__ */ new Map();
+  for (const [name, entry] of Object.entries(manifest.operations)) {
+    if (!/^[_A-Za-z][_0-9A-Za-z]*$/.test(name) || !isRecord(entry) || typeof entry.hash !== "string" || !operationHash.test(entry.hash) || entry.kind !== "query" && entry.kind !== "mutation") {
+      throw new OrmClientError(`invalid operations manifest entry "${name}" \u2014 regenerate the manifest`);
+    }
+    hashes.set(name, entry.hash);
+  }
+  return hashes;
+}
+function createOperationExecutorWithTransport({ namespace, manifest, transport }) {
+  if (typeof namespace !== "string" || !NAMESPACE_PATTERN.test(namespace)) throw new OrmClientError("invalid ORM namespace \u2014 expected a lowercase identifier of at most 41 characters");
+  const hashes = readManifestHashes(manifest);
+  const knownHashes = new Set(hashes.values());
+  return {
+    async execute(op, variables = {}) {
+      const hash = hashes.get(op) ?? (knownHashes.has(op) ? op : void 0);
+      if (!hash) throw new OrmClientError(`unknown operation "${op}" \u2014 not in the manifest (${hashes.size} known). Re-run seq-studio orm generate.`);
+      if (!isRecord(variables)) throw new OrmClientError("operation variables must be an object");
+      const response = await transport({ namespace, op: hash, variables });
+      if (!response || typeof response.ok !== "boolean" || !Number.isInteger(response.status) || response.status < 100 || response.status > 599 || response.ok !== (response.status >= 200 && response.status < 300)) {
+        throw new OrmOperationError("malformed transport response", null, null);
+      }
+      return readOperationResponse(response);
+    }
+  };
+}
+
+// src/orm.ts
+var FunctionOrmError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  name = "FunctionOrmError";
+};
+function readToken({ request }) {
+  const { headers } = request;
+  let value;
+  if (typeof headers.get === "function") {
+    value = headers.get(ORM_DATA_TOKEN_HEADER);
+  } else {
+    const matches = Object.entries(headers).filter(([name]) => name.toLowerCase() === ORM_DATA_TOKEN_HEADER);
+    if (matches.length > 1) throw invalidContext();
+    value = matches[0]?.[1];
+  }
+  if (value === void 0 || value === null || value === "") {
+    throw new FunctionOrmError(
+      "MISSING_CALLER_CONTEXT",
+      "Caller ORM access is unavailable. Declare the function data binding and invoke it through the platform as a signed-in user."
+    );
+  }
+  if (typeof value !== "string" || value.length > 32768) throw invalidContext();
+  return value;
+}
+function invalidContext() {
+  return new FunctionOrmError("INVALID_CALLER_CONTEXT", "The invocation has no valid function caller context.");
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function callerExpiry({ token }) {
+  const parts = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/.exec(token);
+  if (!parts?.[1]) throw invalidContext();
+  let claims;
+  try {
+    claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+  } catch {
+    throw invalidContext();
+  }
+  if (!record(claims) || typeof claims.sub !== "string" || !claims.sub || typeof claims.functionId !== "string" || !claims.functionId || typeof claims.invocationId !== "string" || !claims.invocationId || typeof claims.exp !== "number" || !Number.isSafeInteger(claims.exp) || claims.origin !== void 0 && claims.origin !== "function") throw invalidContext();
+  if (claims.sub.startsWith("service-account|") || claims.sub.endsWith("@clients") || claims.assertedBy != null) {
+    throw new FunctionOrmError(
+      "UNSUPPORTED_CALLER",
+      "This ORM helper requires a direct human invocation. Service-account and system-runner invocations are not supported."
+    );
+  }
+  return claims.exp;
+}
+function requireUnexpired({ expiresAt }) {
+  if (expiresAt <= Math.floor(Date.now() / 1e3)) {
+    throw new FunctionOrmError(
+      "EXPIRED_CALLER_CONTEXT",
+      "The caller context has expired. Start a new platform invocation; do not reuse its executor."
+    );
+  }
+}
+function trustedOrigin({ baseUrl }) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new FunctionOrmError("INVALID_CONFIGURATION", "Configure an absolute platform origin for caller ORM access.");
+  }
+  const localHttp = url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !localHttp || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new FunctionOrmError(
+      "INVALID_CONFIGURATION",
+      "Configure an HTTPS platform origin without credentials, path, query or fragment. HTTP is supported only on loopback for local development."
+    );
+  }
+  return url.origin;
+}
+function createFunctionOrmExecutor({
+  request,
+  baseUrl,
+  namespace,
+  manifest,
+  fetchImpl = globalThis.fetch
+}) {
+  const origin = trustedOrigin({ baseUrl });
+  const token = readToken({ request });
+  const expiresAt = callerExpiry({ token });
+  requireUnexpired({ expiresAt });
+  if (typeof fetchImpl !== "function") {
+    throw new FunctionOrmError("INVALID_CONFIGURATION", "Caller ORM access requires a fetch implementation.");
+  }
+  return createOperationExecutorWithTransport({
+    namespace,
+    manifest,
+    transport: async ({ namespace: targetNamespace, op, variables }) => {
+      requireUnexpired({ expiresAt });
+      const response = await fetchImpl(`${origin}/_data/v2/${targetNamespace}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", [ORM_DATA_TOKEN_HEADER]: token },
+        body: JSON.stringify({ op, variables }),
+        redirect: "error"
+      });
+      const body = await response.json().catch(() => null);
+      return { ok: response.ok, status: response.status, body };
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FunctionOrmError,
+  OrmClientError,
+  OrmOperationError,
+  createFunctionOrmExecutor
+});

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@sequenceholdings/managed-functions",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Managed Function context and opt-in cache runtime",
   "license": "UNLICENSED",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "orm": [
+        "dist/orm.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,6 +21,10 @@
       "types": "./dist/config.d.ts",
       "default": "./dist/config.js"
     },
+    "./orm": {
+      "types": "./dist/orm.d.ts",
+      "default": "./dist/orm.js"
+    },
     "./runtime": "./dist/runtime.cjs"
   },
   "files": [
@@ -35,13 +46,15 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.11",
-    "esbuild": "^0.25.0"
+    "esbuild": "^0.25.0",
+    "tsup": "^8.3.0",
+    "@sequenceholdings/orm": "2.1.1"
   },
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc && node scripts/bundle-runtime.mjs",
+    "build": "tsc && node scripts/bundle-orm.mjs && node scripts/bundle-runtime.mjs",
     "type-check": "tsc --noEmit",
     "test": "vitest run"
   }