pgkiln 0.73.0 → 0.74.0

package/src/remote-servers.ts

@@ -0,0 +1,133 @@
+import { owner } from './db.ts';
+import { WebError } from './webclient.ts';
+
+// (sprint 141, AP-7; APEX: Remote Servers) A named base URL per workspace
+// (meta.remote_server, migration 141): REST data sources (rest_source.server),
+// REST source catalogs (rest_catalog.server) and AI services
+// (ai_service.server_id) name a server and a path instead of a full URL, so
+// moving from development to production changes one value. The URL is this
+// installation's (base_url), or the server's environment variable
+// PGKILN_SERVER_<...> when it is set (env_var wins). Only the prefix
+// PGKILN_SERVER_ may be named, so no other variable of the server's
+// environment (DATABASE_URL, keys) can become a URL or show up in a message.
+//
+// Resolving happens here, with the owner pool (the runtime role can't read
+// the table), always within the application's own workspace: another
+// workspace's server is never found. The URL it gives goes through every
+// check a full URL went through (src/webclient.ts: allow-list, the
+// workspace's network access list, address checks at connect time).
+
+export interface RemoteServer {
+  id: number;
+  workspace_id: number;
+  static_id: string;
+  name: string;
+  description: string | null;
+  base_url: string | null;
+  env_var: string | null;
+  credential: string | null;
+}
+
+export const STATIC_ID = /^[A-Z][A-Z0-9_]{0,59}$/;
+export const ENV_PREFIX = 'PGKILN_SERVER_';
+export const ENV_VAR = /^PGKILN_SERVER_[A-Z0-9_]{1,60}$/;
+const BASE_URL = /^https?:\/\/[^\s<>"{}?#]+$/i;
+
+/** Problems with a base URL (empty: fine): http(s), no trailing slash, query, fragment or user name. */
+export function baseUrlProblem(url: string): string | null {
+  if (!BASE_URL.test(url) || url.length > 2000) return 'The base URL starts with http:// or https://, without spaces, {parameters}, a query or a fragment, e.g. https://crm.example.com/api.';
+  if (url.endsWith('/')) return 'The base URL ends without a slash: the paths after it start with one.';
+  try {
+    const u = new URL(url);
+    if (u.username || u.password) return 'The base URL may not contain a user name or password: use a web credential.';
+  } catch {
+    return 'The base URL is not valid.';
+  }
+  return null;
+}
+
+/** Problems with a server's fields (empty: fine). */
+export function serverProblems(v: { static_id?: unknown; name?: unknown; base_url?: unknown; env_var?: unknown; credential?: unknown; description?: unknown }): string[] {
+  const out: string[] = [];
+  if (typeof v.static_id !== 'string' || !STATIC_ID.test(v.static_id)) out.push('The static id is upper case letters, digits and _, starting with a letter (at most 60), e.g. CRM.');
+  if (typeof v.name !== 'string' || !/^\S(.{0,98}\S)?$/.test(v.name)) out.push('The name is 1 to 100 characters, without spaces at the start or end.');
+  if (v.base_url != null && v.base_url !== '') {
+    const p = baseUrlProblem(String(v.base_url));
+    if (p) out.push(p);
+  }
+  if (v.env_var != null && v.env_var !== '' && (typeof v.env_var !== 'string' || !ENV_VAR.test(v.env_var)))
+    out.push(`The environment variable starts with ${ENV_PREFIX}, then upper case letters, digits and _, e.g. ${ENV_PREFIX}CRM.`);
+  if (!v.base_url && !v.env_var) out.push('Give the base URL, an environment variable that holds it, or both.');
+  if (v.credential != null && v.credential !== '' && (typeof v.credential !== 'string' || !STATIC_ID.test(v.credential))) out.push('The web credential is the name of one, e.g. CRM_API.');
+  if (v.description != null && (typeof v.description !== 'string' || v.description.length > 2000)) out.push('The description is at most 2000 characters.');
+  return out;
+}
+
+/**
+ * The URL a server stands for now: its environment variable when that is set (and valid), else its
+ * stored base URL. `problem` says why there is none (the variable's value is never repeated).
+ */
+export function serverUrl(s: Pick<RemoteServer, 'static_id' | 'base_url' | 'env_var'>): { url: string | null; from: 'env' | 'stored' | null; problem: string | null } {
+  if (s.env_var && ENV_VAR.test(s.env_var)) {
+    const v = (process.env[s.env_var] ?? '').trim().replace(/\/+$/, '');
+    if (v) {
+      if (baseUrlProblem(v)) return { url: null, from: 'env', problem: `Remote server ${s.static_id}: the server's ${s.env_var} is not a valid base URL (http:// or https://, no query).` };
+      return { url: v, from: 'env', problem: null };
+    }
+  }
+  if (s.base_url && !baseUrlProblem(s.base_url)) return { url: s.base_url, from: 'stored', problem: null };
+  return { url: null, from: null, problem: `Remote server ${s.static_id} has no base URL${s.env_var ? ` (and ${s.env_var} is not set on the server)` : ''}.` };
+}
+
+/** "https://crm.example.com/api" + "/orders/{id}" (a path, a query, or nothing). */
+export function joinUrl(base: string, path: string | null | undefined) {
+  const p = (path ?? '').trim();
+  if (!p) return base;
+  return p.startsWith('/') || p.startsWith('?') ? `${base}${p}` : `${base}/${p}`;
+}
+
+/** A server of a workspace by static id (owner pool), or null. */
+export async function workspaceServer(workspaceId: number, staticId: string): Promise<RemoteServer | null> {
+  return (await owner.one<RemoteServer>('select * from meta.remote_server where workspace_id = $1 and static_id = $2', [workspaceId, staticId.toUpperCase()])) ?? null;
+}
+
+/** A server of the application's own workspace by static id, or null. */
+export async function serverForApp(appId: number, staticId: string): Promise<RemoteServer | null> {
+  return (await owner.one<RemoteServer>(
+    'select * from meta.remote_server where workspace_id = meta.app_workspace($1) and static_id = $2', [appId, staticId.toUpperCase()])) ?? null;
+}
+
+/** The full URL of a path on a server of the application's workspace; throws a WebError when it can't be made. */
+export async function appServerUrl(appId: number, staticId: string, path: string | null | undefined) {
+  const s = await serverForApp(appId, staticId);
+  if (!s) throw new WebError(`Remote server ${staticId.toUpperCase()} does not exist in this application's workspace (Workspace utilities → Remote servers).`);
+  const u = serverUrl(s);
+  if (!u.url) throw new WebError(u.problem!);
+  return { url: joinUrl(u.url, path), server: s };
+}
+
+/**
+ * A REST data source as the request code expects it: on a server, its URL becomes the server's base
+ * URL plus the source's path, and a source without a credential of its own uses the server's.
+ */
+export async function resolveSource<T extends { app_id: number; url: string; credential: string | null; server?: string | null }>(src: T): Promise<T> {
+  if (!src.server) return src;
+  const { url, server } = await appServerUrl(src.app_id, src.server, src.url);
+  // resolved once: server null, so resolving again changes nothing
+  return { ...src, url, credential: src.credential || server.credential || null, server: null };
+}
+
+/** The base URL of a catalog on a server of its workspace (null: none, or the catalog has no server). */
+export async function catalogServerUrl(workspaceId: number, staticId: string | null | undefined): Promise<string | null> {
+  if (!staticId) return null;
+  const s = await workspaceServer(workspaceId, staticId);
+  return s ? serverUrl(s).url : null;
+}
+
+/** The base URL of an AI service on a server (any workspace: administrators chose it), or an error message. */
+export async function aiServerUrl(serverId: number, path: string | null | undefined): Promise<{ url: string | null; problem: string | null }> {
+  const s = await owner.one<RemoteServer>('select * from meta.remote_server where id = $1', [serverId]);
+  if (!s) return { url: null, problem: 'Its remote server no longer exists.' };
+  const u = serverUrl(s);
+  return u.url ? { url: joinUrl(u.url, path), problem: null } : { url: null, problem: u.problem };
+}

package/src/restcatalog.ts

@@ -32,7 +32,10 @@ export interface CatalogService {
 export interface Catalog {
   name: string;
   description: string | null;
+  /** (141) may be empty when the catalog is on a remote server */
   base_url: string;
+  /** (141) a remote server of the workspace (static id): data sources made from the catalog use it */
+  server?: string | null;
   source: 'manual' | 'openapi';
   api_version: string | null;
   services: CatalogService[];
@@ -54,10 +57,14 @@ export const trimBase = (url: string) => url.trim().replace(/\/+$/, '');
 export const serviceUrl = (baseUrl: string, path: string) => `${trimBase(baseUrl)}${path}`;
 
 /** Problems with a catalog's own fields (empty: fine). */
-export function catalogProblems(c: { name?: unknown; base_url?: unknown; description?: unknown; api_version?: unknown }): string[] {
+export function catalogProblems(c: { name?: unknown; base_url?: unknown; server?: unknown; description?: unknown; api_version?: unknown }): string[] {
   const out: string[] = [];
   if (typeof c.name !== 'string' || !CATALOG_NAME.test(c.name)) out.push('The name is 1 to 60 characters, without spaces at the start or end.');
-  if (typeof c.base_url !== 'string' || !/^https?:\/\/[^\s<>"{}]+$/i.test(c.base_url) || c.base_url.length > 2000) out.push('The base URL starts with http:// or https://, without spaces or {parameters}, e.g. https://api.example.com/v1.');
+  if (c.server != null && c.server !== '' && (typeof c.server !== 'string' || !SERVICE_NAME.test(c.server))) out.push('The remote server is its static id, e.g. CRM.');
+  // (141) on a remote server the base URL is optional (the document's, kept for reference)
+  if (c.server && (c.base_url == null || c.base_url === '')) {
+    // nothing to check
+  } else if (typeof c.base_url !== 'string' || !/^https?:\/\/[^\s<>"{}]+$/i.test(c.base_url) || c.base_url.length > 2000) out.push('The base URL starts with http:// or https://, without spaces or {parameters}, e.g. https://api.example.com/v1.');
   else if (c.base_url.endsWith('/')) out.push('The base URL ends without a slash: the services\' paths start with one.');
   else {
     try {
@@ -97,7 +104,7 @@ export function wholeCatalogProblems(c: Catalog): string[] {
     if (seen.has(s.name)) out.push(`Service ${s.name} is there twice.`);
     seen.add(s.name);
     // (enough to fix the first ones: a big broken document would list thousands)
-    if (out.length < 50) out.push(...serviceProblems(typeof c.base_url === 'string' ? c.base_url : 'https://x', s));
+    if (out.length < 50) out.push(...serviceProblems(typeof c.base_url === 'string' && c.base_url ? c.base_url : 'https://x', s));
   }
   return out;
 }
@@ -470,6 +477,7 @@ export function catalogDocument(c: Catalog) {
     name: c.name,
     description: c.description,
     base_url: c.base_url,
+    ...(c.server ? { server: c.server } : {}),
     source: c.source,
     api_version: c.api_version,
     services: c.services.map((s) => ({
@@ -487,6 +495,7 @@ export function fromCatalogDocument(doc: Json): Catalog {
     name: String(doc.name ?? ''),
     description: str(doc.description),
     base_url: String(doc.base_url ?? ''),
+    ...(typeof doc.server === 'string' && doc.server ? { server: doc.server } : {}),
     source: doc.source === 'openapi' ? 'openapi' : 'manual',
     api_version: str(doc.api_version),
     services: (Array.isArray(doc.services) ? doc.services : []).map((s: Json) => ({
@@ -554,9 +563,9 @@ export async function loadCatalog(id: number | string, db: Q = owner): Promise<S
 /** Insert a checked catalog into a workspace (inside the caller's transaction); its id. */
 export async function insertCatalog(db: Q, workspaceId: number, c: Catalog, by: string | null): Promise<number> {
   const { id } = (await db.query(
-    `insert into meta.rest_catalog (workspace_id, name, description, base_url, source, api_version, created_by)
-     values ($1, $2, $3, $4, $5, $6, $7) returning id`,
-    [workspaceId, c.name, c.description, c.base_url, c.source, c.api_version, by],
+    `insert into meta.rest_catalog (workspace_id, name, description, base_url, source, api_version, created_by, server)
+     values ($1, $2, $3, $4, $5, $6, $7, $8) returning id`,
+    [workspaceId, c.name, c.description, c.base_url || null, c.source, c.api_version, by, c.server || null],
   )).rows[0];
   await insertServices(db, id, c.services);
   return id;
@@ -565,8 +574,8 @@ export async function insertCatalog(db: Q, workspaceId: number, c: Catalog, by:
 /** Replace a catalog's fields and services (inside the caller's transaction). */
 export async function replaceCatalog(db: Q, id: number, c: Catalog) {
   await db.query(
-    `update meta.rest_catalog set name = $2, description = $3, base_url = $4, source = $5, api_version = $6, updated_at = now() where id = $1`,
-    [id, c.name, c.description, c.base_url, c.source, c.api_version],
+    `update meta.rest_catalog set name = $2, description = $3, base_url = $4, source = $5, api_version = $6, server = $7, updated_at = now() where id = $1`,
+    [id, c.name, c.description, c.base_url || null, c.source, c.api_version, c.server || null],
   );
   await db.query('delete from meta.rest_catalog_service where catalog_id = $1', [id]);
   await insertServices(db, id, c.services);
@@ -587,11 +596,13 @@ async function insertServices(db: Q, catalogId: number, services: CatalogService
  * The values of a REST data source made from a catalog service (meta.rest_source
  * columns): the full URL and a copy of the request and response settings.
  */
-export function sourceFromService(c: { base_url: string; name: string }, s: CatalogService, opts: { name?: string; credential?: string | null } = {}) {
+export function sourceFromService(c: { base_url: string | null; name: string; server?: string | null }, s: CatalogService, opts: { name?: string; credential?: string | null } = {}) {
   return {
     name: (opts.name?.trim() || s.name).toUpperCase(),
     description: s.description ?? `From the REST source catalog ${c.name}.`,
-    url: serviceUrl(c.base_url, s.path),
+    // (141) a catalog on a remote server: the source names the server and the service's path
+    url: c.server ? s.path : serviceUrl(c.base_url ?? '', s.path),
+    server: c.server || null,
     method: s.method,
     credential: opts.credential?.trim() ? opts.credential.trim().toUpperCase() : null,
     params: s.params,

package/src/restsync.ts

@@ -74,7 +74,7 @@ async function loadSyncSource(id: number) {
   return owner.one<SyncSource>(
     `select s.id, s.app_id, s.name, s.url, s.method, s.credential, s.headers, s.params, s.body, s.row_selector, s.columns, s.cache_seconds,
             s.timeout_s, s.max_rows, s.key_columns, s.operations, s.sync_table, s.sync_mode, s.sync_delete, s.sync_schedule, s.sync_time_zone,
-            s.sync_enabled, a.db_role
+            s.sync_enabled, s.server, a.db_role
        from meta.rest_source s join meta.app a on a.id = s.app_id where s.id = $1`,
     [id],
   );

package/src/runtime/context.ts

@@ -120,6 +120,8 @@ export function bindValues(ctx: PageContext): BindValues {
 /** Replace &NAME. substitution strings (APEX syntax); `encode` escapes each value. */
 export function substitute(text: string, ctx: PageContext, encode: (v: string) => string) {
   const values = bindValues(ctx);
+  // (141) #APP_FILES# and #WORKSPACE_FILES#: where the application's and its workspace's static files are served
+  if (text.includes('_FILES#')) text = text.replace(/#(APP|WORKSPACE)_FILES#/g, (_, kind: string) => `${ctx.base}/${kind === 'APP' ? 'static' : 'workspace-files'}/`);
   return text.replace(/&([A-Za-z][A-Za-z0-9_]*(?:\$[A-Za-z0-9_.-]+?)?)\./g, (m, name: string) => {
     const upper = name.toUpperCase();
     if (upper.startsWith('APP_TEXT$')) {

package/src/runtime/static-files.ts

@@ -6,10 +6,15 @@
 // inline. HTML (and anything else a browser would run as a document) is
 // refused by the database and by the type list below, and SVG is served
 // with a policy of its own so a script in it never runs.
-import type { FastifyInstance } from 'fastify';
+// (sprint 141, AP-7) Static workspace files (meta.workspace_file) are served
+// the same way to every application of their workspace, at
+// /a/<alias>/workspace-files/<name>; lists name them #WORKSPACE_FILES#<name>,
+// templates and settings use #APP_FILES# and #WORKSPACE_FILES# (context.ts
+// substitute, template-components.ts rowLookup).
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
 import { html } from '../html.ts';
-import { runtime } from '../db.ts';
-import { loadApp } from '../metadata.ts';
+import { owner, runtime } from '../db.ts';
+import { loadApp, type StaticInclude } from '../metadata.ts';
 import type { PageContext } from './context.ts';
 import { pluginsOnPage } from './plugins.ts';
 
@@ -43,17 +48,51 @@ export function staticHead(ctx: PageContext) {
   // the plug-ins' files (at their version) after the application's, then the page's
   const version = new Map<string, number>((ctx.app.static_files ?? []).map((f) => [f.name, f.v]));
   const pluginFiles = pluginsOnPage(ctx).flatMap((p) => p.files.filter((n) => version.has(n)).map((name) => ({ name, v: version.get(name)! })));
-  const files = [...(ctx.app.static_includes ?? []), ...pluginFiles, ...(ctx.page.static_includes ?? [])];
+  const files: StaticInclude[] = [...(ctx.app.static_includes ?? []), ...pluginFiles, ...(ctx.page.static_includes ?? [])];
   const seen = new Set<string>();
   return files
-    .filter((f) => includable(f.name) && !seen.has(f.name) && seen.add(f.name))
+    .filter((f) => includable(f.name) && !seen.has(`${f.ws ? 'w' : 'a'}:${f.name}`) && seen.add(`${f.ws ? 'w' : 'a'}:${f.name}`))
     .map((f) => {
-      const src = `${ctx.base}/static/${encodeURIComponent(f.name)}?v=${f.v}`;
+      // (141) a static workspace file: from the workspace of this application, on its own origin
+      const src = `${ctx.base}/${f.ws ? 'workspace-files' : 'static'}/${encodeURIComponent(f.name)}?v=${f.v}`;
       return /\.css$/i.test(f.name) ? html`<link rel="stylesheet" href="${src}">` : html`<script src="${src}" defer></script>`;
     });
 }
 
+/** Send a static file with the headers both kinds share (type, cache, a policy for SVG and PDF). */
+function sendFile(req: FastifyRequest<{ Querystring: { v?: string } }>, reply: FastifyReply, type: string, f: { content: Buffer; v: string }) {
+  const etag = `"${Number(f.v).toString(36)}"`;
+  reply
+    .type(type.startsWith('text/') ? `${type}; charset=utf-8` : type)
+    .header('etag', etag)
+    // never sniffed into something else (the app's pages set it too; a file may be fetched on its own)
+    .header('x-content-type-options', 'nosniff')
+    // a versioned link (?v=…, as pages write them) never changes; a bare one is checked again
+    .header('cache-control', req.query.v ? 'public, max-age=31536000, immutable' : 'no-cache');
+  // opened on its own, an SVG or PDF is a document: no scripts, no requests
+  if (type === 'image/svg+xml' || type === 'application/pdf')
+    reply.header('content-security-policy', `default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'${type === 'image/svg+xml' ? '; sandbox' : ''}`);
+  if (req.headers['if-none-match'] === etag) return reply.code(304).send();
+  return reply.send(f.content);
+}
+
+/** (141) A static workspace file to serve to an application: its own workspace's only (the owner pool). */
+export async function workspaceFileFor(alias: string, name: string) {
+  return owner.one<{ content: Buffer; v: string }>(
+    `select f.content, floor(extract(epoch from f.updated_at) * 1000)::bigint::text as v
+       from meta.app a join meta.workspace_file f on f.workspace_id = meta.app_workspace(a.id) and f.name = $2
+      where a.alias = $1`, [alias, name]);
+}
+
 export async function staticFileRoutes(app: FastifyInstance) {
+  // (141) static workspace files, served to every application of the workspace on its own origin
+  app.get<{ Params: { alias: string; name: string }; Querystring: { v?: string } }>('/a/:alias/workspace-files/:name', async (req, reply) => {
+    const type = staticType(req.params.name);
+    const f = type ? await workspaceFileFor(req.params.alias, req.params.name) : null;
+    if (!f) return reply.code(404).type('text/plain').send('Not found');
+    return sendFile(req, reply, type!, f);
+  });
+
   app.get<{ Params: { alias: string; name: string }; Querystring: { v?: string } }>('/a/:alias/static/:name', async (req, reply) => {
     const type = staticType(req.params.name);
     const a = type ? await loadApp(req.params.alias) : null;
@@ -61,16 +100,6 @@ export async function staticFileRoutes(app: FastifyInstance) {
       ? await runtime.one<{ content: Buffer; v: string }>('select content, floor(extract(epoch from updated_at) * 1000)::bigint::text as v from meta.static_file where app_id = $1 and name = $2', [a.id, req.params.name])
       : null;
     if (!f) return reply.code(404).type('text/plain').send('Not found');
-    const etag = `"${Number(f.v).toString(36)}"`;
-    reply
-      .type(type!.startsWith('text/') ? `${type}; charset=utf-8` : type!)
-      .header('etag', etag)
-      // a versioned link (?v=…, as pages write them) never changes; a bare one is checked again
-      .header('cache-control', req.query.v ? 'public, max-age=31536000, immutable' : 'no-cache');
-    // opened on its own, an SVG or PDF is a document: no scripts, no requests
-    if (type === 'image/svg+xml' || type === 'application/pdf')
-      reply.header('content-security-policy', `default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'${type === 'image/svg+xml' ? '; sandbox' : ''}`);
-    if (req.headers['if-none-match'] === etag) return reply.code(304).send();
-    return reply.send(f.content);
+    return sendFile(req, reply, type!, f);
   });
 }

package/src/runtime/template-components.ts

@@ -573,7 +573,8 @@ export function attributeValues(c: TemplateComponent, use: TcUse) {
  * filled in), then LINK, APEX$ROW_NUM, then the row's columns.
  */
 export function rowLookup(ctx: PageContext | null, attrs: Map<string, string>, columns: Map<string, string>, extra: Record<string, string | undefined> = {}): Lookup {
-  const col: Lookup = (n) => columns.get(n) ?? extra[n];
+  // (141) #APP_FILES# / #WORKSPACE_FILES#: where the application's and its workspace's static files are served
+  const col: Lookup = (n) => columns.get(n) ?? extra[n] ?? (ctx && (n === 'APP_FILES' || n === 'WORKSPACE_FILES') ? `${ctx.base}/${n === 'APP_FILES' ? 'static' : 'workspace-files'}/` : undefined);
   const memo = new Map<string, string>();
   return (name) => {
     if (attrs.has(name)) {

package/src/websources.ts

@@ -5,6 +5,7 @@ import { runtimeForApp } from './workspace-db.ts';
 import { decryptSecret, encryptSecret } from './secrets.ts';
 import { checkUrl, WebError, webRequest, type OutboundScope, type WebResponse } from './webclient.ts';
 import { scopeForApp } from './network-acl.ts';
+import { resolveSource } from './remote-servers.ts';
 
 // Web credentials and REST data sources (meta.web_credential,
 // meta.rest_source): building the request (parameters, credential), OAuth2
@@ -34,6 +35,8 @@ export interface WebCredential {
   oauth_username?: string | null;
   password_enc?: string | null;
   refresh_token_enc?: string | null;
+  /** (141) a credential of the application's workspace (meta.workspace_credential) */
+  workspace?: boolean;
 }
 
 export type ParamLocation = 'query' | 'path' | 'header' | 'body';
@@ -56,9 +59,12 @@ export interface RestSource {
   id: number;
   app_id: number;
   name: string;
+  /** a full URL; (141) with a server, the path after the server's base URL (resolveSource makes it full) */
   url: string;
   method: string;
   credential: string | null;
+  /** (141) a remote server of the application's workspace (static id) */
+  server?: string | null;
   headers: Record<string, string>;
   params: RestParam[];
   body: string | null;
@@ -101,9 +107,14 @@ const RESERVED_HEADERS = new Set(['authorization', 'proxy-authorization', 'cooki
 // ---------------------------------------------------------------- checks (builder, import)
 
 /** Problems with a REST data source definition (empty: fine). */
-export function sourceProblems(s: { url?: unknown; params?: unknown; columns?: unknown; headers?: unknown; row_selector?: unknown; key_columns?: unknown; operations?: unknown }): string[] {
+export function sourceProblems(s: { url?: unknown; server?: unknown; params?: unknown; columns?: unknown; headers?: unknown; row_selector?: unknown; key_columns?: unknown; operations?: unknown }): string[] {
   const out: string[] = [];
-  if (typeof s.url !== 'string' || !/^https?:\/\/[^/\s]+/i.test(s.url)) out.push('The URL must start with http:// or https://.');
+  if (s.server != null && s.server !== '') {
+    // (141) on a remote server: a path after its base URL (or nothing)
+    if (typeof s.server !== 'string' || !/^[A-Z][A-Z0-9_]{0,59}$/.test(s.server)) out.push('The remote server is its static id, e.g. CRM.');
+    if (typeof s.url !== 'string' || !/^([/?][^\s]*)?$/.test(s.url)) out.push('With a remote server the URL is the path after its base URL, e.g. /v1/orders/{id} (or empty).');
+    else if (s.url.includes('//') || /(^|\/)\.\.?(\/|$|\?)/.test(s.url)) out.push('The path may not contain // or .. segments.');
+  } else if (typeof s.url !== 'string' || !/^https?:\/\/[^/\s]+/i.test(s.url)) out.push('The URL must start with http:// or https://.');
   else if (/[{&]/.test(/^https?:\/\/[^/?#]*/i.exec(s.url)![0])) out.push('The URL\'s host is fixed: parameters can only follow it.');
   else {
     try {
@@ -384,21 +395,29 @@ export const withRest = (rowsQuery: string, sql: string | null | undefined) =>
 export async function loadSource(appId: number, name: string) {
   // the application's own connection (an isolated workspace's), also from a workflow or job (090)
   const s = await (await runtimeForApp(appId)).one<RestSource>(
-    `select id, app_id, name, url, method, credential, headers, params, body, row_selector, columns, cache_seconds, timeout_s, max_rows, key_columns, operations
+    `select id, app_id, name, url, method, credential, server, headers, params, body, row_selector, columns, cache_seconds, timeout_s, max_rows, key_columns, operations
        from meta.rest_source where app_id = $1 and name = $2`,
     [appId, name.toUpperCase()],
   );
   if (!s) throw new WebError(`REST data source ${name} does not exist.`);
-  return s;
+  // (141) on a remote server: the server's URL of this moment, and its credential when the source names none
+  return resolveSource(s);
 }
 
-/** With the (encrypted) secret: the owner connection, never the runtime role. */
+const CREDENTIAL_COLUMNS = 'id, name, type, username, header_name, token_url, scope, valid_for, secret_enc, grant_type, oauth_username, password_enc, refresh_token_enc';
+
+/**
+ * With the (encrypted) secret: the owner connection, never the runtime role. The application's own
+ * credential of that name, else (141) one of its workspace's (never another workspace's).
+ */
 export async function loadCredential(appId: number, name: string) {
-  const c = await owner.one<WebCredential>(
-    `select id, app_id, name, type, username, header_name, token_url, scope, valid_for, secret_enc, grant_type, oauth_username, password_enc, refresh_token_enc
-       from meta.web_credential where app_id = $1 and name = $2`,
+  const c = (await owner.one<WebCredential>(
+    `select ${CREDENTIAL_COLUMNS}, app_id from meta.web_credential where app_id = $1 and name = $2`,
     [appId, name.toUpperCase()],
-  );
+  )) ?? (await owner.one<WebCredential>(
+    `select ${CREDENTIAL_COLUMNS}, $1::int as app_id, true as workspace from meta.workspace_credential where workspace_id = meta.app_workspace($1) and name = $2`,
+    [appId, name.toUpperCase()],
+  ));
   if (!c) throw new WebError(`Web credential ${name} does not exist.`);
   return c;
 }
@@ -428,15 +447,18 @@ interface Token {
 const tokens = new Map<string, Token>();
 const pendingTokens = new Map<string, Promise<Token>>();
 const credKey = (c: WebCredential) =>
-  createHash('sha256').update(JSON.stringify([c.id, c.username, c.token_url, c.scope, c.secret_enc, c.grant_type ?? null, c.oauth_username ?? null, c.password_enc ?? null])).digest('base64url');
+  createHash('sha256').update(JSON.stringify([tokenId(c), c.username, c.token_url, c.scope, c.secret_enc, c.grant_type ?? null, c.oauth_username ?? null, c.password_enc ?? null])).digest('base64url');
+
+/** The token cache's id of a credential: (141) a workspace credential's starts with w. */
+const tokenId = (c: Pick<WebCredential, 'id' | 'workspace'>) => (c.workspace ? `w${c.id}` : String(c.id));
 
-/** Forget cached tokens (all, or one credential's). */
-export function clearTokens(credentialId?: number) {
+/** Forget cached tokens (all, or one credential's: its id, or w<id> for a workspace credential). */
+export function clearTokens(credentialId?: number | string) {
   for (const k of [...tokens.keys()]) if (credentialId === undefined || k.startsWith(`${credentialId}:`)) tokens.delete(k);
 }
 
 const secretOf = (c: WebCredential) => {
-  if (!c.secret_enc) throw new WebError(`Web credential ${c.name} has no secret yet: enter it in the builder (Shared Components → Web credentials).`);
+  if (!c.secret_enc) throw new WebError(`Web credential ${c.name} has no secret yet: enter it in the builder (${c.workspace ? 'Workspace utilities' : 'Shared Components'} → Web credentials).`);
   return decryptSecret(c.secret_enc);
 };
 
@@ -504,7 +526,7 @@ async function requestToken(c: WebCredential, refresh: string | null, timeoutMs:
 /** Keep a refresh token (encrypted); written with the owner connection only. */
 async function storeRefreshToken(c: WebCredential, token: string) {
   const enc = encryptSecret(token);
-  await owner.query('update meta.web_credential set refresh_token_enc = $2, token_refreshed_at = now() where id = $1', [c.id, enc]);
+  await owner.query(`update meta.${c.workspace ? 'workspace_credential' : 'web_credential'} set refresh_token_enc = $2, token_refreshed_at = now() where id = $1`, [c.id, enc]);
   c.refresh_token_enc = enc;
 }
 
@@ -519,7 +541,7 @@ function storedRefresh(c: WebCredential) {
 }
 
 async function oauthToken(c: WebCredential, timeoutMs: number, scope: OutboundScope | null, fresh = false): Promise<string> {
-  const key = `${c.id}:${credKey(c)}`;
+  const key = `${tokenId(c)}:${credKey(c)}`;
   const cached = tokens.get(key);
   if (cached && !fresh && cached.expires > Date.now()) return cached.access;
   let p = pendingTokens.get(key);
@@ -609,7 +631,7 @@ export async function call(o: CallOptions): Promise<WebResponse> {
   };
   const res = await send(false);
   if (res.status === 401 && o.credential?.type === 'oauth2') {
-    clearTokens(o.credential.id);
+    clearTokens(tokenId(o.credential));
     return send(true);
   }
   return res;
@@ -759,7 +781,8 @@ export function buildOperation(s: RestSource, name: OperationName, row: Record<s
  * 200–299 fails. Returns the response's JSON (null when empty) and, for
  * insert and fetch, the row in it (by the operation's row selector).
  */
-export async function callOperation(s: RestSource, name: OperationName, row: Record<string, unknown>, params: Record<string, string> = {}) {
+export async function callOperation(source: RestSource, name: OperationName, row: Record<string, unknown>, params: Record<string, string> = {}) {
+  const s = await resolveSource(source);
   const req = buildOperation(s, name, row, params);
   const credential = s.credential ? await loadCredential(s.app_id, s.credential) : null;
   const res = await call({ ...req, appId: s.app_id, what: `REST data source ${s.name}`, credential, timeoutMs: s.timeout_s * 1000 });
@@ -790,7 +813,9 @@ export function clearResponseCache(sourceId?: number) {
 }
 
 /** The parsed JSON response of a source (from the cache when it is fresh enough). */
-export async function fetchSource(s: RestSource, values: Record<string, string | null | undefined>) {
+export async function fetchSource(source: RestSource, values: Record<string, string | null | undefined>) {
+  // (141) on a remote server: its URL now (a source from loadSource is resolved already)
+  const s = await resolveSource(source);
   const req = buildRequest(s, values);
   // (sprint 118) the workspace's network access list, before the cache: a narrowed list applies at once
   const scope = await scopeForApp(s.app_id, `REST data source ${s.name}`);

package/src/workspace-export.ts

@@ -2,6 +2,9 @@ import type { Client } from './db.ts';
 import { owner } from './db.ts';
 import { checkDataset, datasetOf, storeDataset } from './datasets.ts';
 import { describeTeam, exportTeam, importTeam } from './team.ts';
+import { serverProblems } from './remote-servers.ts';
+import { STATIC_MAX, staticType } from './runtime/static-files.ts';
+import { credentialProblems, GRANT_TYPES } from './websources.ts';
 import { catalogDocument, fromCatalogDocument, insertCatalog, loadCatalog, replaceCatalog, wholeCatalogProblems } from './restcatalog.ts';
 
 // Workspace utilities → Export / import (APEX: Workspace Utilities → Export,
@@ -21,6 +24,10 @@ import { catalogDocument, fromCatalogDocument, insertCatalog, loadCatalog, repla
 //   datasets         (sprint 110) Data Reporter datasets (pgkiln-dataset/1 definitions)
 //   team             (sprint 113) Team Development: label groups, labels, milestones, templates and issues
 //                    (with comments and history; applications by alias), an object (src/team.ts)
+//   workspace_files  (sprint 141) static workspace files (content in base64)
+//   remote_servers   (sprint 141) remote servers; an existing server keeps its own base URL on import
+//                    (the URL is per installation: development, test, production)
+//   web_credentials  (sprint 141) the workspace's web credentials, never their secrets (entered again after an import)
 //
 // Not exported: the workspace's name (the importer's workspace keeps its own),
 // isolation and its database roles (installation-specific), script runs and
@@ -29,7 +36,8 @@ import { catalogDocument, fromCatalogDocument, insertCatalog, loadCatalog, repla
 // installation has a developer of that name.
 
 export const WORKSPACE_FORMAT = 'pgkiln-workspace/1';
-export const PARTS = ['settings', 'developers', 'app_groups', 'extension_links', 'rest_catalogs', 'sql_scripts', 'blueprints', 'data_generators', 'datasets', 'team'] as const;
+export const PARTS = ['settings', 'developers', 'app_groups', 'extension_links', 'rest_catalogs', 'sql_scripts', 'blueprints', 'data_generators', 'datasets', 'team',
+  'workspace_files', 'remote_servers', 'web_credentials'] as const;
 export type Part = (typeof PARTS)[number];
 export const PART_LABELS: Record<Part, string> = {
   settings: 'Settings: description, message, banner and preferences',
@@ -42,6 +50,9 @@ export const PART_LABELS: Record<Part, string> = {
   data_generators: 'Data generators',
   datasets: 'Data Reporter datasets',
   team: 'Team Development: labels, milestones, templates and issues',
+  workspace_files: 'Static workspace files',
+  remote_servers: 'Remote servers (an existing server keeps its base URL)',
+  web_credentials: 'Web credentials (without their secrets)',
 };
 
 const MAX_ITEMS = 5000;
@@ -82,6 +93,14 @@ export async function exportWorkspace(workspaceId: number, parts: readonly Part[
   if (want('datasets'))
     doc.datasets = (await owner.query('select * from meta.dataset where workspace_id = $1 order by name', [workspaceId])).rows.map(datasetOf);
   if (want('team')) doc.team = await exportTeam(workspaceId);
+  if (want('workspace_files'))
+    doc.workspace_files = (await owner.query(`select name, mime, translate(encode(content, 'base64'), E'\n', '') as content from meta.workspace_file where workspace_id = $1 order by name`, [workspaceId])).rows;
+  if (want('remote_servers'))
+    doc.remote_servers = (await owner.query('select static_id, name, description, base_url, env_var, credential from meta.remote_server where workspace_id = $1 order by static_id', [workspaceId])).rows;
+  if (want('web_credentials'))
+    // secrets never leave the installation
+    doc.web_credentials = (await owner.query(
+      'select name, description, type, username, header_name, token_url, scope, valid_for, grant_type, oauth_username from meta.workspace_credential where workspace_id = $1 order by name', [workspaceId])).rows;
   return doc;
 }
 
@@ -271,5 +290,65 @@ export async function importWorkspace(c: Client, workspaceId: number, doc: unkno
     const t = await importTeam(c, workspaceId, d.team, opts);
     tally('Team Development', t.added, t.replaced, t.skipped, t.issues ? `; ${t.issues} issue(s) with their comments` : '');
   }
+
+  if (want('workspace_files')) {
+    // (sprint 141) the same names, types and sizes as an upload
+    const n = count();
+    for (const x of d.workspace_files as Json[]) {
+      const name = isObj(x) && typeof x.name === 'string' ? x.name : '';
+      const type = staticType(name);
+      if (!type) throw new Error(`Static workspace file ${JSON.stringify(name).slice(0, 110)}: not an allowed name or type.`);
+      const content = typeof x.content === 'string' ? Buffer.from(x.content, 'base64') : Buffer.alloc(0);
+      if (content.length > STATIC_MAX) throw new Error(`Static workspace file ${name}: larger than ${STATIC_MAX / 1024 / 1024} MB.`);
+      const existing = (await c.query<{ id: number }>('select id from meta.workspace_file where workspace_id = $1 and name = $2', [workspaceId, name])).rows[0];
+      n[await upsert(existing,
+        () => c.query('insert into meta.workspace_file (workspace_id, name, mime, content, updated_by) values ($1, $2, $3, $4, $5)', [workspaceId, name, type, content, opts.by]),
+        (id) => c.query('update meta.workspace_file set mime = $2, content = $3, updated_by = $4, updated_at = now() where id = $1', [id, type, content, opts.by]))]++;
+    }
+    tally('Static workspace files', n.added, n.replaced, n.skipped);
+  }
+
+  if (want('remote_servers')) {
+    // (sprint 141) the base URL is this installation's: an existing server keeps its own, a new one takes the file's
+    const n = count();
+    for (const x of d.remote_servers as Json[]) {
+      if (!isObj(x)) continue;
+      const v = { static_id: x.static_id, name: x.name, description: text(x.description, 2000), base_url: text(x.base_url, 2000), env_var: text(x.env_var, 80), credential: text(x.credential, 60) };
+      const problems = serverProblems(v);
+      if (problems.length) throw new Error(`Remote server ${typeof x.static_id === 'string' ? x.static_id : '?'}: ${problems.join(' ')}`);
+      const existing = (await c.query<{ id: number }>('select id from meta.remote_server where workspace_id = $1 and static_id = $2', [workspaceId, v.static_id])).rows[0];
+      n[await upsert(existing,
+        () => c.query('insert into meta.remote_server (workspace_id, static_id, name, description, base_url, env_var, credential, updated_by) values ($1, $2, $3, $4, $5, $6, $7, $8)',
+          [workspaceId, v.static_id, v.name, v.description, v.base_url, v.env_var, v.credential, opts.by]),
+        (id) => c.query(`update meta.remote_server set name = $2, description = $3, env_var = $4, credential = $5, base_url = coalesce(base_url, $6),
+                                updated_by = $7, updated_at = now() where id = $1`, [id, v.name, v.description, v.env_var, v.credential, v.base_url, opts.by]))]++;
+    }
+    tally('Remote servers', n.added, n.replaced, n.skipped, n.replaced ? '; existing servers kept their base URL' : '');
+  }
+
+  if (want('web_credentials')) {
+    // (sprint 141) without secrets: an existing credential keeps its own, a new one gets them entered in the builder
+    const n = count();
+    for (const x of d.web_credentials as Json[]) {
+      if (!isObj(x)) continue;
+      const v = {
+        name: String(x.name ?? ''), description: text(x.description, 2000),
+        type: ['basic', 'header', 'bearer', 'oauth2', 'aws_sigv4'].includes(x.type) ? x.type : 'basic',
+        username: text(x.username, 500), header_name: text(x.header_name, 64), token_url: text(x.token_url, 2000), scope: text(x.scope, 500),
+        valid_for: Array.isArray(x.valid_for) ? x.valid_for.filter((u: unknown) => typeof u === 'string') : [],
+        grant_type: GRANT_TYPES.includes(x.grant_type) ? x.grant_type : 'client_credentials', oauth_username: text(x.oauth_username, 500),
+      };
+      const problems = [...(/^[A-Z][A-Z0-9_]{0,59}$/.test(v.name) ? [] : ['the name is upper case letters, digits and _.']), ...credentialProblems(v)];
+      if (problems.length) throw new Error(`Web credential ${v.name || '?'}: ${problems.join(' ')}`);
+      const vals = [v.description, v.type, v.username, v.header_name, v.token_url, v.scope, v.valid_for, v.grant_type, v.oauth_username];
+      const existing = (await c.query<{ id: number }>('select id from meta.workspace_credential where workspace_id = $1 and name = $2', [workspaceId, v.name])).rows[0];
+      n[await upsert(existing,
+        () => c.query(`insert into meta.workspace_credential (workspace_id, name, description, type, username, header_name, token_url, scope, valid_for, grant_type, oauth_username, updated_by)
+                       values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)`, [workspaceId, v.name, ...vals, opts.by]),
+        (id) => c.query(`update meta.workspace_credential set description = $2, type = $3, username = $4, header_name = $5, token_url = $6, scope = $7, valid_for = $8,
+                                grant_type = $9, oauth_username = $10, updated_by = $11, updated_at = now() where id = $1`, [id, ...vals, opts.by]))]++;
+    }
+    tally('Web credentials', n.added, n.replaced, n.skipped, n.added ? '; enter their secrets under Workspace utilities → Web credentials' : '');
+  }
   return r;
 }