@volter/world-core 3.0.69 → 3.0.71

package/capability-decision.cjs

@@ -8,7 +8,7 @@ const { allowsWorldNetworkEgress, isWorldInternalHost, worldNetworkNeedsPathInsp
 
 /** The declaration of a guest with no declaration format: an ordinary host process, which can reach what the host can.
  *  Its own loopback is what it observably opened (`facts.ownListener`). A substrate whose guest can declare never uses it. */
-const OPEN_DECLARATION = Object.freeze({ network: Object.freeze({ egress: '*', services: '*', host: true }) });
+const OPEN_DECLARATION = Object.freeze({ network: Object.freeze({ egress: '*', services: '*', host: true }), files: Object.freeze({ host: true }) });
 
 /** What an unreadable declaration, or one bound to another World, declares: nothing. */
 const EMPTY_DECLARATION = Object.freeze({ network: Object.freeze({}) });
@@ -216,6 +216,44 @@ function decideEgress(request, context) {
   return pass(capability, target, policy && worldNetworkUsesPassthrough(policy, url) ? 'passthrough' : 'direct');
 }
 
+/** `path` as a normalized absolute POSIX path, or null: `.` and `..` resolved, no symlink followed (that is I/O). */
+function normalPath(path) {
+  if (typeof path !== 'string' || !path.startsWith('/') || path.includes('\0')) return null;
+  const parts = [];
+  for (const segment of path.split('/')) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') parts.pop(); else parts.push(segment);
+  }
+  return `/${parts.join('/')}`;
+}
+function within(path, root) {
+  const base = normalPath(root);
+  return !!base && (path === base || path.startsWith(base === '/' ? '/' : `${base}/`));
+}
+
+/**
+ * A file the guest reads (`request.path`). It reads its own tree (`files.tree`, implicit for an image) at `facts.tree`,
+ * the World's provided files (`facts.worldFiles`), the measured system paths (`facts.system`) and its declared mounts
+ * (`files.mounts`) inside the World's root (`facts.worldRoot`); a host process reads the host's files (`files.host`).
+ */
+function decideRead(request, { declaration, facts = {} }) {
+  const capability = 'files.read';
+  const target = String(request.path);
+  const path = normalPath(target);
+  const files = (declaration && declaration.files) || {};
+  if (!path) return refuse(capability, target, 'declaration', 'read-invalid', `${target} is not an absolute path`, declaration);
+  if (files.host === true) return pass(capability, path, 'host');
+  if (files.tree === true && facts.tree && within(path, facts.tree)) return pass(capability, path, 'own-tree');
+  if ((facts.worldFiles || []).some((root) => within(path, root))) return pass(capability, path, 'world');
+  if ((facts.system || []).some((root) => within(path, root))) return pass(capability, path, 'system');
+  const mount = (Array.isArray(files.mounts) ? files.mounts : []).find((root) => within(path, root));
+  if (mount) {
+    return facts.worldRoot && within(normalPath(mount) || '', facts.worldRoot) ? pass(capability, path, 'mount')
+      : refuse(capability, path, 'grant', 'mount-outside-world', `the mount ${mount} is outside this World's folder: no World grants a host path it does not own; mount it from inside the World's folder`, declaration);
+  }
+  return refuse(capability, path, 'declaration', 'read-undeclared', `in Docker this container cannot read ${path}: it sees its own filesystem, the World's files and its declared mounts; declare a mount`, declaration);
+}
+
 /** Whether the World's build-phase grant lists `url` itself, which then wins over a twin of its host. */
 function publicBuildGrant(grant, url) {
   return grant.strict !== true && !!grant.policy && grant.policy.phase === 'build' && allowsWorldNetworkEgress(grant.policy, url);
@@ -231,14 +269,15 @@ function decidePersist(request, { declaration }) {
 }
 
 /**
- * A connection the decision let through that the run's sandbox refused (a native image run's Seatbelt answers EPERM):
- * the enforcer's rendering is narrower than the decision. One text for every reporter: the injector for Node, the
- * images CLI's kernel-log reporter for other programs (whose target is `*:<port>`: the kernel masks the address).
+ * A connection the decision let through that a native image run's Seatbelt profile refused (EPERM): the native run
+ * admits only the World proxy and loopback, so the World sees each request, and a client that dials out directly fails
+ * there. One text for every reporter: the injector for Node, the images CLI's kernel-log reporter for other programs
+ * (whose target is `*:<port>`: the kernel masks the address). The profile reproduces Docker; it is no containment.
  */
 function sandboxRefusal(target) {
-  return refuse('network.egress', target, 'transport', 'sandbox',
-    `the run's sandbox refused a connection to ${target} that the World's decision let through: the sandbox admits only `
-    + 'the World proxy and loopback, so a client reaches other hosts through the World proxy (HTTPS_PROXY)');
+  return refuse('network.egress', target, 'transport', 'native-direct',
+    `the native run reaches ${target} only through the World proxy, and this client dialled it directly; `
+    + 'send it through the World proxy (HTTPS_PROXY)');
 }
 
 /**
@@ -249,12 +288,14 @@ function decideCapability(request, context) {
   if (request.kind === 'egress') return decideEgress(request, context);
   if (request.kind === 'loopback') return decideLoopback(request, context);
   if (request.kind === 'persist') return decidePersist(request, context);
+  if (request.kind === 'read') return decideRead(request, context);
   throw new Error(`Unknown capability request: ${request.kind}`);
 }
 
 /**
  * The same rules evaluated up front, for an enforcer that renders a profile instead of asking per connection (a native
- * image run's Seatbelt profile). `world.endpoints`: [{ host, port, kind: 'door' | 'service', name }].
+ * image run's Seatbelt profile). `world.endpoints`: [{ host, port, kind: 'door' | 'service', name }]; `world.files`:
+ * { tree, worldFiles, system, worldRoot }, the read facts.
  * Egress is `proxy` when declared: twin routing and the per-request listing are the World proxy's, which a profile
  * forces traffic through; `none` when the guest declares none.
  */
@@ -280,7 +321,20 @@ function decideCapabilitySet(declaration, grant = {}, world = {}) {
     const answer = decidePersist({ path }, context);
     if (answer.outcome === 'pass') persist.push(path); else refusals.push(answer);
   }
-  return Object.freeze({ network: Object.freeze({ egress, loopback, listen, endpoints }), files: Object.freeze({ persist }), refusals: Object.freeze(refusals) });
+  const facts = world.files || {};
+  const declared = (declaration && declaration.files) || {};
+  const read = [];
+  if (declared.host === true) read.push({ path: '/', kind: 'host' });
+  else {
+    if (declared.tree === true && facts.tree) read.push({ path: normalPath(facts.tree), kind: 'own-tree' });
+    for (const root of facts.worldFiles || []) read.push({ path: normalPath(root), kind: 'world' });
+    for (const root of facts.system || []) read.push({ path: normalPath(root), kind: 'system' });
+    for (const mount of Array.isArray(declared.mounts) ? declared.mounts : []) {
+      const answer = decideRead({ path: mount }, { declaration, facts: { worldRoot: facts.worldRoot } });
+      if (answer.outcome === 'pass') read.push({ path: normalPath(mount), kind: 'mount' }); else refusals.push(answer);
+    }
+  }
+  return Object.freeze({ network: Object.freeze({ egress, loopback, listen, endpoints }), files: Object.freeze({ persist, read: Object.freeze(read.filter((r) => r.path)) }), refusals: Object.freeze(refusals) });
 }
 
 module.exports = { OPEN_DECLARATION, EMPTY_DECLARATION, WORLD_DECLARATION_ENV, GRANT_FIELDS, worldDeclarationFromEnv, publicBuildGrant, decideCapability, decideCapabilitySet, sandboxRefusal, refusalRecord, refusalSide };

package/capability-decision.d.cts

@@ -1,6 +1,6 @@
 import type { WorldNetworkPolicy } from './network-policy.cjs';
 
-export type CapabilityName = 'network.egress' | 'network.ownLoopback' | 'network.services' | 'network.host' | 'files.persist';
+export type CapabilityName = 'network.egress' | 'network.ownLoopback' | 'network.services' | 'network.host' | 'files.read' | 'files.persist';
 export type RefusalSide = 'declaration' | 'grant' | 'transport' | 'twin';
 export type DeclaredBy = { readonly capability: CapabilityName; readonly file: string; readonly line: number };
 
@@ -13,7 +13,7 @@ export interface CapabilityDeclaration {
     readonly services?: '*' | readonly string[];
     readonly host?: boolean;
   };
-  readonly files?: { readonly persist?: readonly string[] };
+  readonly files?: { readonly persist?: readonly string[]; readonly tree?: boolean; readonly mounts?: readonly string[]; readonly host?: boolean };
   readonly derivedFrom?: readonly DeclaredBy[];
 }
 
@@ -27,16 +27,22 @@ export interface CapabilityFacts {
   readonly guestProxy?: URL | null;
   readonly endpoint?: Pick<WorldEndpoint, 'kind' | 'name'> | null;
   readonly ownListener?: boolean;
+  /** read facts: the run's tree, the World's provided files, the measured system paths, the World's root */
+  readonly tree?: string;
+  readonly worldFiles?: readonly string[];
+  readonly system?: readonly string[];
+  readonly worldRoot?: string;
 }
 export interface CapabilityContext { readonly run?: { readonly guest?: boolean }; readonly declaration?: CapabilityDeclaration; readonly grant?: WorldGrant; readonly facts?: CapabilityFacts }
 
 export type CapabilityRequest =
   | { readonly kind: 'egress'; readonly url: string | URL | null; readonly method?: string; readonly transport?: 'http' | 'upgrade' | 'http2' | 'dispatch' | 'socket' | 'datagram'; readonly port?: number }
   | { readonly kind: 'loopback'; readonly host: string; readonly port?: number; readonly transport?: 'tcp' | 'udp' }
-  | { readonly kind: 'persist'; readonly path: string };
+  | { readonly kind: 'persist'; readonly path: string }
+  | { readonly kind: 'read'; readonly path: string };
 
 export type CapabilityAnswer =
-  | { readonly outcome: 'pass'; readonly capability: CapabilityName; readonly target: string; readonly via: 'direct' | 'inspected' | 'passthrough' | 'guest-proxy' | 'run-scoped' }
+  | { readonly outcome: 'pass'; readonly capability: CapabilityName; readonly target: string; readonly via: 'direct' | 'inspected' | 'passthrough' | 'guest-proxy' | 'run-scoped' | 'host' | 'own-tree' | 'world' | 'system' | 'mount' }
   | { readonly outcome: 'twin'; readonly capability: CapabilityName; readonly target: string; readonly twin: { readonly vendor: string; readonly origin: string } }
   | { readonly outcome: 'refuse'; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly rule: string; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy; readonly see?: string };
 
@@ -44,7 +50,7 @@ export interface WorldRefusalRecord { readonly kind: 'volter-world-refusal'; rea
 
 export interface CapabilitySet {
   readonly network: { readonly egress: 'none' | 'proxy'; readonly loopback: 'none' | 'own'; readonly listen: readonly number[]; readonly endpoints: readonly WorldEndpoint[] };
-  readonly files: { readonly persist: readonly string[] };
+  readonly files: { readonly persist: readonly string[]; readonly read: readonly { readonly path: string; readonly kind: 'host' | 'own-tree' | 'world' | 'system' | 'mount' }[] };
   readonly refusals: readonly Extract<CapabilityAnswer, { outcome: 'refuse' }>[];
 }
 
@@ -56,6 +62,6 @@ export function sandboxRefusal(target: string): Extract<CapabilityAnswer, { outc
 export const GRANT_FIELDS: Readonly<Partial<Record<CapabilityName, string>>>;
 export function publicBuildGrant(grant: WorldGrant, url: URL): boolean;
 export function decideCapability(request: CapabilityRequest, context: CapabilityContext): CapabilityAnswer;
-export function decideCapabilitySet(declaration: CapabilityDeclaration | undefined, grant?: WorldGrant, world?: { readonly endpoints?: readonly WorldEndpoint[] }): CapabilitySet;
+export function decideCapabilitySet(declaration: CapabilityDeclaration | undefined, grant?: WorldGrant, world?: { readonly endpoints?: readonly WorldEndpoint[]; readonly files?: { readonly tree?: string; readonly worldFiles?: readonly string[]; readonly system?: readonly string[]; readonly worldRoot?: string } }): CapabilitySet;
 export function refusalRecord(answer: Extract<CapabilityAnswer, { outcome: 'refuse' }>): WorldRefusalRecord;
 export function refusalSide(answer: Extract<CapabilityAnswer, { outcome: 'refuse' }>): string;

package/dist/capability-decision.cjs

@@ -8,7 +8,7 @@ const { allowsWorldNetworkEgress, isWorldInternalHost, worldNetworkNeedsPathInsp
 
 /** The declaration of a guest with no declaration format: an ordinary host process, which can reach what the host can.
  *  Its own loopback is what it observably opened (`facts.ownListener`). A substrate whose guest can declare never uses it. */
-const OPEN_DECLARATION = Object.freeze({ network: Object.freeze({ egress: '*', services: '*', host: true }) });
+const OPEN_DECLARATION = Object.freeze({ network: Object.freeze({ egress: '*', services: '*', host: true }), files: Object.freeze({ host: true }) });
 
 /** What an unreadable declaration, or one bound to another World, declares: nothing. */
 const EMPTY_DECLARATION = Object.freeze({ network: Object.freeze({}) });
@@ -216,6 +216,44 @@ function decideEgress(request, context) {
   return pass(capability, target, policy && worldNetworkUsesPassthrough(policy, url) ? 'passthrough' : 'direct');
 }
 
+/** `path` as a normalized absolute POSIX path, or null: `.` and `..` resolved, no symlink followed (that is I/O). */
+function normalPath(path) {
+  if (typeof path !== 'string' || !path.startsWith('/') || path.includes('\0')) return null;
+  const parts = [];
+  for (const segment of path.split('/')) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') parts.pop(); else parts.push(segment);
+  }
+  return `/${parts.join('/')}`;
+}
+function within(path, root) {
+  const base = normalPath(root);
+  return !!base && (path === base || path.startsWith(base === '/' ? '/' : `${base}/`));
+}
+
+/**
+ * A file the guest reads (`request.path`). It reads its own tree (`files.tree`, implicit for an image) at `facts.tree`,
+ * the World's provided files (`facts.worldFiles`), the measured system paths (`facts.system`) and its declared mounts
+ * (`files.mounts`) inside the World's root (`facts.worldRoot`); a host process reads the host's files (`files.host`).
+ */
+function decideRead(request, { declaration, facts = {} }) {
+  const capability = 'files.read';
+  const target = String(request.path);
+  const path = normalPath(target);
+  const files = (declaration && declaration.files) || {};
+  if (!path) return refuse(capability, target, 'declaration', 'read-invalid', `${target} is not an absolute path`, declaration);
+  if (files.host === true) return pass(capability, path, 'host');
+  if (files.tree === true && facts.tree && within(path, facts.tree)) return pass(capability, path, 'own-tree');
+  if ((facts.worldFiles || []).some((root) => within(path, root))) return pass(capability, path, 'world');
+  if ((facts.system || []).some((root) => within(path, root))) return pass(capability, path, 'system');
+  const mount = (Array.isArray(files.mounts) ? files.mounts : []).find((root) => within(path, root));
+  if (mount) {
+    return facts.worldRoot && within(normalPath(mount) || '', facts.worldRoot) ? pass(capability, path, 'mount')
+      : refuse(capability, path, 'grant', 'mount-outside-world', `the mount ${mount} is outside this World's folder: no World grants a host path it does not own; mount it from inside the World's folder`, declaration);
+  }
+  return refuse(capability, path, 'declaration', 'read-undeclared', `in Docker this container cannot read ${path}: it sees its own filesystem, the World's files and its declared mounts; declare a mount`, declaration);
+}
+
 /** Whether the World's build-phase grant lists `url` itself, which then wins over a twin of its host. */
 function publicBuildGrant(grant, url) {
   return grant.strict !== true && !!grant.policy && grant.policy.phase === 'build' && allowsWorldNetworkEgress(grant.policy, url);
@@ -231,14 +269,15 @@ function decidePersist(request, { declaration }) {
 }
 
 /**
- * A connection the decision let through that the run's sandbox refused (a native image run's Seatbelt answers EPERM):
- * the enforcer's rendering is narrower than the decision. One text for every reporter: the injector for Node, the
- * images CLI's kernel-log reporter for other programs (whose target is `*:<port>`: the kernel masks the address).
+ * A connection the decision let through that a native image run's Seatbelt profile refused (EPERM): the native run
+ * admits only the World proxy and loopback, so the World sees each request, and a client that dials out directly fails
+ * there. One text for every reporter: the injector for Node, the images CLI's kernel-log reporter for other programs
+ * (whose target is `*:<port>`: the kernel masks the address). The profile reproduces Docker; it is no containment.
  */
 function sandboxRefusal(target) {
-  return refuse('network.egress', target, 'transport', 'sandbox',
-    `the run's sandbox refused a connection to ${target} that the World's decision let through: the sandbox admits only `
-    + 'the World proxy and loopback, so a client reaches other hosts through the World proxy (HTTPS_PROXY)');
+  return refuse('network.egress', target, 'transport', 'native-direct',
+    `the native run reaches ${target} only through the World proxy, and this client dialled it directly; `
+    + 'send it through the World proxy (HTTPS_PROXY)');
 }
 
 /**
@@ -249,12 +288,14 @@ function decideCapability(request, context) {
   if (request.kind === 'egress') return decideEgress(request, context);
   if (request.kind === 'loopback') return decideLoopback(request, context);
   if (request.kind === 'persist') return decidePersist(request, context);
+  if (request.kind === 'read') return decideRead(request, context);
   throw new Error(`Unknown capability request: ${request.kind}`);
 }
 
 /**
  * The same rules evaluated up front, for an enforcer that renders a profile instead of asking per connection (a native
- * image run's Seatbelt profile). `world.endpoints`: [{ host, port, kind: 'door' | 'service', name }].
+ * image run's Seatbelt profile). `world.endpoints`: [{ host, port, kind: 'door' | 'service', name }]; `world.files`:
+ * { tree, worldFiles, system, worldRoot }, the read facts.
  * Egress is `proxy` when declared: twin routing and the per-request listing are the World proxy's, which a profile
  * forces traffic through; `none` when the guest declares none.
  */
@@ -280,7 +321,20 @@ function decideCapabilitySet(declaration, grant = {}, world = {}) {
     const answer = decidePersist({ path }, context);
     if (answer.outcome === 'pass') persist.push(path); else refusals.push(answer);
   }
-  return Object.freeze({ network: Object.freeze({ egress, loopback, listen, endpoints }), files: Object.freeze({ persist }), refusals: Object.freeze(refusals) });
+  const facts = world.files || {};
+  const declared = (declaration && declaration.files) || {};
+  const read = [];
+  if (declared.host === true) read.push({ path: '/', kind: 'host' });
+  else {
+    if (declared.tree === true && facts.tree) read.push({ path: normalPath(facts.tree), kind: 'own-tree' });
+    for (const root of facts.worldFiles || []) read.push({ path: normalPath(root), kind: 'world' });
+    for (const root of facts.system || []) read.push({ path: normalPath(root), kind: 'system' });
+    for (const mount of Array.isArray(declared.mounts) ? declared.mounts : []) {
+      const answer = decideRead({ path: mount }, { declaration, facts: { worldRoot: facts.worldRoot } });
+      if (answer.outcome === 'pass') read.push({ path: normalPath(mount), kind: 'mount' }); else refusals.push(answer);
+    }
+  }
+  return Object.freeze({ network: Object.freeze({ egress, loopback, listen, endpoints }), files: Object.freeze({ persist, read: Object.freeze(read.filter((r) => r.path)) }), refusals: Object.freeze(refusals) });
 }
 
 module.exports = { OPEN_DECLARATION, EMPTY_DECLARATION, WORLD_DECLARATION_ENV, GRANT_FIELDS, worldDeclarationFromEnv, publicBuildGrant, decideCapability, decideCapabilitySet, sandboxRefusal, refusalRecord, refusalSide };

package/dist/capability-decision.d.cts

@@ -1,6 +1,6 @@
 import type { WorldNetworkPolicy } from './network-policy.cjs';
 
-export type CapabilityName = 'network.egress' | 'network.ownLoopback' | 'network.services' | 'network.host' | 'files.persist';
+export type CapabilityName = 'network.egress' | 'network.ownLoopback' | 'network.services' | 'network.host' | 'files.read' | 'files.persist';
 export type RefusalSide = 'declaration' | 'grant' | 'transport' | 'twin';
 export type DeclaredBy = { readonly capability: CapabilityName; readonly file: string; readonly line: number };
 
@@ -13,7 +13,7 @@ export interface CapabilityDeclaration {
     readonly services?: '*' | readonly string[];
     readonly host?: boolean;
   };
-  readonly files?: { readonly persist?: readonly string[] };
+  readonly files?: { readonly persist?: readonly string[]; readonly tree?: boolean; readonly mounts?: readonly string[]; readonly host?: boolean };
   readonly derivedFrom?: readonly DeclaredBy[];
 }
 
@@ -27,16 +27,22 @@ export interface CapabilityFacts {
   readonly guestProxy?: URL | null;
   readonly endpoint?: Pick<WorldEndpoint, 'kind' | 'name'> | null;
   readonly ownListener?: boolean;
+  /** read facts: the run's tree, the World's provided files, the measured system paths, the World's root */
+  readonly tree?: string;
+  readonly worldFiles?: readonly string[];
+  readonly system?: readonly string[];
+  readonly worldRoot?: string;
 }
 export interface CapabilityContext { readonly run?: { readonly guest?: boolean }; readonly declaration?: CapabilityDeclaration; readonly grant?: WorldGrant; readonly facts?: CapabilityFacts }
 
 export type CapabilityRequest =
   | { readonly kind: 'egress'; readonly url: string | URL | null; readonly method?: string; readonly transport?: 'http' | 'upgrade' | 'http2' | 'dispatch' | 'socket' | 'datagram'; readonly port?: number }
   | { readonly kind: 'loopback'; readonly host: string; readonly port?: number; readonly transport?: 'tcp' | 'udp' }
-  | { readonly kind: 'persist'; readonly path: string };
+  | { readonly kind: 'persist'; readonly path: string }
+  | { readonly kind: 'read'; readonly path: string };
 
 export type CapabilityAnswer =
-  | { readonly outcome: 'pass'; readonly capability: CapabilityName; readonly target: string; readonly via: 'direct' | 'inspected' | 'passthrough' | 'guest-proxy' | 'run-scoped' }
+  | { readonly outcome: 'pass'; readonly capability: CapabilityName; readonly target: string; readonly via: 'direct' | 'inspected' | 'passthrough' | 'guest-proxy' | 'run-scoped' | 'host' | 'own-tree' | 'world' | 'system' | 'mount' }
   | { readonly outcome: 'twin'; readonly capability: CapabilityName; readonly target: string; readonly twin: { readonly vendor: string; readonly origin: string } }
   | { readonly outcome: 'refuse'; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly rule: string; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy; readonly see?: string };
 
@@ -44,7 +50,7 @@ export interface WorldRefusalRecord { readonly kind: 'volter-world-refusal'; rea
 
 export interface CapabilitySet {
   readonly network: { readonly egress: 'none' | 'proxy'; readonly loopback: 'none' | 'own'; readonly listen: readonly number[]; readonly endpoints: readonly WorldEndpoint[] };
-  readonly files: { readonly persist: readonly string[] };
+  readonly files: { readonly persist: readonly string[]; readonly read: readonly { readonly path: string; readonly kind: 'host' | 'own-tree' | 'world' | 'system' | 'mount' }[] };
   readonly refusals: readonly Extract<CapabilityAnswer, { outcome: 'refuse' }>[];
 }
 
@@ -56,6 +62,6 @@ export function sandboxRefusal(target: string): Extract<CapabilityAnswer, { outc
 export const GRANT_FIELDS: Readonly<Partial<Record<CapabilityName, string>>>;
 export function publicBuildGrant(grant: WorldGrant, url: URL): boolean;
 export function decideCapability(request: CapabilityRequest, context: CapabilityContext): CapabilityAnswer;
-export function decideCapabilitySet(declaration: CapabilityDeclaration | undefined, grant?: WorldGrant, world?: { readonly endpoints?: readonly WorldEndpoint[] }): CapabilitySet;
+export function decideCapabilitySet(declaration: CapabilityDeclaration | undefined, grant?: WorldGrant, world?: { readonly endpoints?: readonly WorldEndpoint[]; readonly files?: { readonly tree?: string; readonly worldFiles?: readonly string[]; readonly system?: readonly string[]; readonly worldRoot?: string } }): CapabilitySet;
 export function refusalRecord(answer: Extract<CapabilityAnswer, { outcome: 'refuse' }>): WorldRefusalRecord;
 export function refusalSide(answer: Extract<CapabilityAnswer, { outcome: 'refuse' }>): string;

package/dist/src/index.d.ts

@@ -67,6 +67,7 @@ export { acceptH2Connection, type H2Handler, type Http1Handler } from './h2.js';
 export { placeholderPng } from './placeholder-image.js';
 export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.js';
 export * as redis from './redis/index.js';
+export * as mysql from './mysql/index.js';
 export * as git from './git/index.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';

package/dist/src/index.js

@@ -59,6 +59,7 @@ export { acceptH2Connection } from "./h2.js";
 export { placeholderPng } from "./placeholder-image.js";
 export { presignSigV4, signSigV4, verifySigV4 } from "./sigv4.js";
 export * as redis from "./redis/index.js";
+export * as mysql from "./mysql/index.js";
 export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";

package/dist/src/mysql/client.d.ts

@@ -0,0 +1,28 @@
+import { type MysqlError } from './stream.js';
+/** Sends bytes and returns every byte the server answered to them. */
+export type MysqlExchange = (bytes: Uint8Array) => Promise<Uint8Array>;
+export type MysqlResultSet = {
+    columns: {
+        name: string;
+        type: number;
+        flags: number;
+    }[];
+    rows: (string | null)[][];
+};
+export type MysqlAnswer = MysqlResultSet | {
+    affectedRows: number;
+    insertId: number;
+} | {
+    error: MysqlError;
+};
+/** Sign in: the server's greeting, then the handshake response (mysql_native_password), following an auth switch. */
+export declare function mysqlSignIn(exchange: MysqlExchange, greeting: Uint8Array, user: string, password: string, database: string | null): Promise<{
+    ok: true;
+} | {
+    error: MysqlError;
+}>;
+/** A text query (COM_QUERY): the first result of a script, as mysql_async reads it. */
+export declare function mysqlQuery(exchange: MysqlExchange, sql: string): Promise<MysqlAnswer>;
+/** A prepared statement executed once with text-typed parameters (COM_STMT_PREPARE, EXECUTE, CLOSE), as Prisma sends a
+ *  parameterised query: binary parameters and rows. */
+export declare function mysqlExecute(exchange: MysqlExchange, sql: string, params: (string | null)[]): Promise<MysqlAnswer>;

package/dist/src/mysql/client.js

@@ -0,0 +1,220 @@
+// A MySQL client over any byte exchange: the other side of ./stream.ts, so a journey speaks the wire as an application's
+// driver does (mysql_async under Prisma's engines): protocol v10 with mysql_native_password, text queries, and prepared
+// statements with binary parameters and rows. It reads what the protocol answers; it decides nothing.
+// source: https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_basics.html
+import { MysqlType, MysqlFlag, nativePasswordToken } from "./stream.js";
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+const CLIENT_CAPS = 0x1 | 0x4 | 0x8 | 0x200 | 0x2000 | 0x8000 | 0x10000 | 0x20000 | 0x40000 | 0x80000 | 0x200000;
+function packet(seq, payload) {
+    const out = new Uint8Array(4 + payload.length);
+    out[0] = payload.length & 0xff;
+    out[1] = (payload.length >> 8) & 0xff;
+    out[2] = (payload.length >> 16) & 0xff;
+    out[3] = seq;
+    out.set(payload, 4);
+    return out;
+}
+function packets(bytes) {
+    const out = [];
+    let at = 0;
+    while (at + 4 <= bytes.length) {
+        const len = bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+        out.push(bytes.subarray(at + 4, at + 4 + len));
+        at += 4 + len;
+    }
+    return out;
+}
+class Cursor {
+    b;
+    at = 0;
+    constructor(b) {
+        this.b = b;
+    }
+    u8() { return this.b[this.at++]; }
+    u16() { return this.u8() | (this.u8() << 8); }
+    u32() { return (this.u16() | (this.u16() << 16)) >>> 0; }
+    u64() { let n = 0n; for (let i = 0n; i < 8n; i++)
+        n |= BigInt(this.u8()) << (8n * i); return n; }
+    take(n) { const out = this.b.subarray(this.at, this.at + n); this.at += n; return out; }
+    nul() { const end = this.b.indexOf(0, this.at); const s = dec.decode(this.b.subarray(this.at, end)); this.at = end + 1; return s; }
+    lenenc() { const f = this.u8(); if (f < 0xfb)
+        return f; if (f === 0xfc)
+        return this.u16(); if (f === 0xfd)
+        return this.u16() | (this.u8() << 16); return Number(this.u64()); }
+    lenencStr() { return dec.decode(this.take(this.lenenc())); }
+}
+const errorOf = (p) => {
+    const c = new Cursor(p);
+    c.u8();
+    const errno = c.u16();
+    c.u8(); // '#'
+    const sqlstate = dec.decode(c.take(5));
+    return { errno, sqlstate, message: dec.decode(c.take(p.length - c.at)) };
+};
+function column(p) {
+    const c = new Cursor(p);
+    c.lenencStr();
+    c.lenencStr();
+    c.lenencStr();
+    c.lenencStr(); // catalog, schema, table, org_table
+    const name = c.lenencStr();
+    c.lenencStr();
+    c.lenenc(); // org_name, fixed-length 0x0c
+    c.u16();
+    c.u32();
+    const type = c.u8();
+    const flags = c.u16();
+    return { name, type, flags };
+}
+const pad = (n, w = 2) => String(n).padStart(w, '0');
+/** A binary row's value as MySQL's text protocol writes it, so a journey reads both protocols alike. */
+function binaryValue(c, type, flags) {
+    const unsigned = (flags & MysqlFlag.UNSIGNED) !== 0;
+    switch (type) {
+        case MysqlType.TINY: {
+            const v = c.u8();
+            return String(unsigned ? v : (v << 24) >> 24);
+        }
+        case MysqlType.SHORT:
+        case MysqlType.YEAR: {
+            const v = c.u16();
+            return String(unsigned ? v : (v << 16) >> 16);
+        }
+        case MysqlType.LONG:
+        case MysqlType.INT24: {
+            const v = c.u32();
+            return String(unsigned ? v : v | 0);
+        }
+        case MysqlType.LONGLONG: {
+            const v = c.u64();
+            return String(unsigned ? v : BigInt.asIntN(64, v));
+        }
+        case MysqlType.FLOAT: {
+            const b = c.take(4);
+            return String(new DataView(b.buffer, b.byteOffset, 4).getFloat32(0, true));
+        }
+        case MysqlType.DOUBLE: {
+            const b = c.take(8);
+            return String(new DataView(b.buffer, b.byteOffset, 8).getFloat64(0, true));
+        }
+        case MysqlType.DATE:
+        case MysqlType.DATETIME:
+        case MysqlType.TIMESTAMP: {
+            const len = c.u8();
+            if (!len)
+                return type === MysqlType.DATE ? '0000-00-00' : '0000-00-00 00:00:00';
+            const y = c.u16(), m = c.u8(), d = c.u8();
+            const [h, i, s] = len >= 7 ? [c.u8(), c.u8(), c.u8()] : [0, 0, 0];
+            const us = len >= 11 ? c.u32() : 0;
+            const day = `${pad(y, 4)}-${pad(m)}-${pad(d)}`;
+            return type === MysqlType.DATE ? day : `${day} ${pad(h)}:${pad(i)}:${pad(s)}${us ? `.${pad(us, 6)}` : ''}`;
+        }
+        case MysqlType.TIME: {
+            const len = c.u8();
+            if (!len)
+                return '00:00:00';
+            const neg = c.u8(), days = c.u32(), h = c.u8(), i = c.u8(), s = c.u8();
+            const us = len >= 12 ? c.u32() : 0;
+            return `${neg ? '-' : ''}${pad(days * 24 + h)}:${pad(i)}:${pad(s)}${us ? `.${pad(us, 6)}` : ''}`;
+        }
+        default: return c.lenencStr();
+    }
+}
+/** One command's answer: an OK, an ERR, or a result set (text or binary rows). */
+function answer(payloads, binary) {
+    const first = payloads[0];
+    if (!first)
+        return { error: { errno: 2013, sqlstate: 'HY000', message: 'Lost connection to MySQL server during query' } };
+    if (first[0] === 0xff)
+        return { error: errorOf(first) };
+    // a result set begins with its column count (never 0): 0x00 is an OK
+    if (first[0] === 0x00) {
+        const c = new Cursor(first);
+        c.u8();
+        return { affectedRows: c.lenenc(), insertId: c.lenenc() };
+    }
+    const c = new Cursor(first);
+    const count = c.lenenc();
+    const columns = payloads.slice(1, 1 + count).map(column);
+    const rows = [];
+    for (const p of payloads.slice(2 + count)) {
+        if (p[0] === 0xfe && p.length < 9)
+            break; // the closing EOF
+        if (p[0] === 0xff)
+            return { error: errorOf(p) };
+        const r = new Cursor(p);
+        if (!binary) {
+            rows.push(columns.map(() => (r.b[r.at] === 0xfb ? (r.at++, null) : r.lenencStr())));
+            continue;
+        }
+        r.u8();
+        const bitmap = r.take(Math.floor((columns.length + 9) / 8));
+        rows.push(columns.map((col, i) => ((bitmap[Math.floor((i + 2) / 8)] >> ((i + 2) % 8)) & 1 ? null : binaryValue(r, col.type, col.flags))));
+    }
+    return { columns, rows };
+}
+/** Sign in: the server's greeting, then the handshake response (mysql_native_password), following an auth switch. */
+export async function mysqlSignIn(exchange, greeting, user, password, database) {
+    const g = new Cursor(packets(greeting)[0]);
+    g.u8();
+    g.nul();
+    g.u32();
+    const part1 = g.take(8);
+    g.u8();
+    g.u16();
+    g.u8();
+    g.u16();
+    g.u16();
+    g.u8();
+    g.take(10);
+    const part2 = g.take(12);
+    const scramble = new Uint8Array([...part1, ...part2]);
+    const token = nativePasswordToken(password, scramble);
+    const body = [...new Uint8Array([CLIENT_CAPS & 0xff, (CLIENT_CAPS >> 8) & 0xff, (CLIENT_CAPS >> 16) & 0xff, (CLIENT_CAPS >> 24) & 0xff, 0, 0, 0, 1, 45]), ...new Array(23).fill(0),
+        ...enc.encode(user), 0, token.length, ...token, ...(database ? [...enc.encode(database), 0] : [0]), ...enc.encode('mysql_native_password'), 0];
+    let reply = packets(await exchange(packet(1, Uint8Array.from(body))))[0];
+    if (reply?.[0] === 0xfe) { // the server asks for another plugin's answer: mysql_native_password with its scramble
+        const c = new Cursor(reply);
+        c.u8();
+        c.nul();
+        reply = packets(await exchange(packet(3, nativePasswordToken(password, c.take(20)))))[0];
+    }
+    if (!reply || reply[0] === 0xff)
+        return { error: reply ? errorOf(reply) : { errno: 2013, sqlstate: 'HY000', message: 'Lost connection to MySQL server during handshake' } };
+    return { ok: true };
+}
+/** A text query (COM_QUERY): the first result of a script, as mysql_async reads it. */
+export async function mysqlQuery(exchange, sql) {
+    return answer(packets(await exchange(packet(0, Uint8Array.from([0x03, ...enc.encode(sql)])))), false);
+}
+/** A prepared statement executed once with text-typed parameters (COM_STMT_PREPARE, EXECUTE, CLOSE), as Prisma sends a
+ *  parameterised query: binary parameters and rows. */
+export async function mysqlExecute(exchange, sql, params) {
+    const prepared = packets(await exchange(packet(0, Uint8Array.from([0x16, ...enc.encode(sql)]))));
+    if (prepared[0]?.[0] === 0xff)
+        return { error: errorOf(prepared[0]) };
+    const c = new Cursor(prepared[0]);
+    c.u8();
+    const id = c.u32();
+    c.u16();
+    const count = c.u16();
+    const head = [0x17, id & 0xff, (id >> 8) & 0xff, (id >> 16) & 0xff, (id >>> 24) & 0xff, 0, 1, 0, 0, 0];
+    const values = [];
+    if (count) {
+        const bitmap = new Array(Math.floor((count + 7) / 8)).fill(0);
+        params.forEach((v, i) => { if (v === null)
+            bitmap[Math.floor(i / 8)] |= 1 << (i % 8); });
+        head.push(...bitmap, 1);
+        for (let i = 0; i < count; i++)
+            head.push(params[i] === null ? MysqlType.NULL : MysqlType.VAR_STRING, 0);
+        for (const v of params)
+            if (v !== null) {
+                const b = enc.encode(v);
+                values.push(...(b.length < 251 ? [b.length] : [0xfc, b.length & 0xff, b.length >> 8]), ...b);
+            }
+    }
+    const result = answer(packets(await exchange(packet(0, Uint8Array.from([...head, ...values])))), true);
+    await exchange(packet(0, Uint8Array.from([0x19, id & 0xff, (id >> 8) & 0xff, (id >> 16) & 0xff, (id >>> 24) & 0xff])));
+    return result;
+}

package/dist/src/mysql/index.d.ts

@@ -0,0 +1,2 @@
+export * from './stream.js';
+export * from './client.js';

package/dist/src/mysql/index.js

@@ -0,0 +1,5 @@
+// THE KERNEL'S MYSQL WIRE (`@volter/world-core/mysql`): MySQL's client/server protocol as a TwinStream. A pack that serves
+// MySQL passes what a statement means (its engine) and whom it admits; the kernel names no vendor.
+// docs/contributing/architecture.md, "Other wires", the MySQL wire.
+export * from "./stream.js";
+export * from "./client.js";