@pikku/core 0.12.96 → 0.12.98

package/dist/wirings/data-lock/data-lock-wiring.d.ts

@@ -0,0 +1,40 @@
+import type { DataLock, LockState } from '../../classification/data-lock.js';
+export type DataLockStatus = {
+    state: LockState;
+    /**
+     * Milliseconds before another guess will be looked at, or 0.
+     *
+     * The unlock screen shows this as a countdown; without it the only way to
+     * learn the wait is over is to guess again, and a guess made during a
+     * lockout is itself a failure that extends it.
+     */
+    retryAfterMs: number;
+};
+export type DataLockWiringOptions = {
+    /** Where the lock routes are mounted. Defaults to `/_pikku/data`. */
+    prefix?: string;
+    /**
+     * Which keys first-run initialization mints. Derive it with
+     * `keyIdsFromManifest`.
+     *
+     * It is fixed here rather than sent by the caller because the unlock screen
+     * posts a passphrase and nothing else — and because a key the schema names
+     * but nobody minted does not fail at startup, it fails at the first write to
+     * that one column.
+     */
+    keyIds?: string[];
+};
+/**
+ * Puts the passphrase gate on HTTP, so unlocking is a page in the app rather
+ * than a prompt in whatever happens to have launched the server.
+ *
+ * That is what lets one story cover both shapes pikku ships in: a desktop
+ * build whose window is pointed at the local server, and a headless
+ * `pikku serve` somewhere else, unlock the same way and share the unlock
+ * screen. A native prompt in the desktop shell would have left the headless
+ * case with nothing.
+ *
+ * The routes are registered here rather than generated because they belong to
+ * core: an app has no source file for them to be discovered in.
+ */
+export declare const wireDataLock: (lock: DataLock, { prefix, keyIds }?: DataLockWiringOptions) => void;

package/dist/wirings/data-lock/data-lock-wiring.js

@@ -0,0 +1,77 @@
+import { pikkuState } from '../../pikku-state.js';
+import { wireHTTP } from '../http/http-runner.js';
+import { httpRouter } from '../http/routers/http-router.js';
+const helperFunctionMeta = (funcId) => ({
+    pikkuFuncId: funcId,
+    sessionless: true,
+    functionType: 'helper',
+    inputSchemaName: null,
+    outputSchemaName: null,
+});
+const DEFAULT_PREFIX = '/_pikku/data';
+/**
+ * Puts the passphrase gate on HTTP, so unlocking is a page in the app rather
+ * than a prompt in whatever happens to have launched the server.
+ *
+ * That is what lets one story cover both shapes pikku ships in: a desktop
+ * build whose window is pointed at the local server, and a headless
+ * `pikku serve` somewhere else, unlock the same way and share the unlock
+ * screen. A native prompt in the desktop shell would have left the headless
+ * case with nothing.
+ *
+ * The routes are registered here rather than generated because they belong to
+ * core: an app has no source file for them to be discovered in.
+ */
+export const wireDataLock = (lock, { prefix = DEFAULT_PREFIX, keyIds } = {}) => {
+    const status = () => ({
+        state: lock.state,
+        retryAfterMs: lock.retryAfterMs,
+    });
+    register(prefix, 'get', '/status', 'pikkuDataLockStatus', async () => status());
+    register(prefix, 'post', '/initialize', 'pikkuDataLockInitialize', async (_services, { passphrase }) => {
+        await lock.initialize(passphrase, keyIds);
+        return status();
+    });
+    register(prefix, 'post', '/unlock', 'pikkuDataLockUnlock', async (_services, { passphrase }) => {
+        await lock.unlock(passphrase);
+        return status();
+    });
+    register(prefix, 'post', '/lock', 'pikkuDataLockLock', async (_services, { passphrase }) => {
+        // Locking proves ownership first. An open POST here would be a
+        // one-request denial of service: the store shuts and stays shut until
+        // someone is around to type the passphrase back in.
+        await lock.unlock(passphrase);
+        lock.lock();
+        return status();
+    });
+    // A router that has already compiled its table would otherwise answer 404
+    // for everything registered after it woke up.
+    httpRouter.reset();
+};
+const register = (prefix, method, path, funcId, func) => {
+    const route = `${prefix}${path}`;
+    const routes = pikkuState(null, 'http', 'routes');
+    if (routes.get(method)?.has(route)) {
+        return;
+    }
+    const httpMeta = pikkuState(null, 'http', 'meta');
+    httpMeta[method][route] = {
+        pikkuFuncId: funcId,
+        route,
+        method,
+        // Never a session. The gate cannot sit in front of its own key: a session
+        // may itself live in a column this lock is holding shut.
+        auth: false,
+        requiresSession: false,
+    };
+    const functionsMeta = pikkuState(null, 'function', 'meta');
+    if (!functionsMeta[funcId]) {
+        functionsMeta[funcId] = helperFunctionMeta(funcId);
+    }
+    wireHTTP({
+        method,
+        route,
+        func: { func },
+        auth: false,
+    });
+};

package/dist/wirings/data-lock/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The HTTP face of {@link DataLock}: the routes an unlock screen talks to.
+ *
+ * Separate from `@pikku/core/classification` on purpose — that entry point is
+ * types and crypto, and a runtime that never serves HTTP should not have to
+ * load a router to use it.
+ */
+export { wireDataLock } from './data-lock-wiring.js';
+export type { DataLockStatus, DataLockWiringOptions, } from './data-lock-wiring.js';

package/dist/wirings/data-lock/index.js

@@ -0,0 +1,8 @@
+/**
+ * The HTTP face of {@link DataLock}: the routes an unlock screen talks to.
+ *
+ * Separate from `@pikku/core/classification` on purpose — that entry point is
+ * types and crypto, and a runtime that never serves HTTP should not have to
+ * load a router to use it.
+ */
+export { wireDataLock } from './data-lock-wiring.js';

package/dist/wirings/virtual-user/virtual-user-scaffold.d.ts

@@ -4,6 +4,7 @@ import type { VariablesService } from '../../services/variables-service.js';
 import type { AgentRunnerService } from '../../services/agent-runner-service.js';
 import type { HttpPersonasConfig } from '../../services/http-personas.js';
 import type { ResolvedPersona, ScenarioPersonas } from '../../services/personas-service.js';
+import type { PersonaEnvironment } from '../persona/persona-environments.js';
 import type { StepRecord, VirtualUserDisposition } from './virtual-user.types.js';
 import type { VirtualUserRunRecord, VirtualUserRunStore } from './virtual-user-run-store.js';
 import type { VirtualUserScheduleRecord, VirtualUserScheduleStore } from './virtual-user-schedule-store.js';
@@ -84,10 +85,15 @@ export interface StartVirtualUserRunParams {
     /**
      * The app's config, read only for `nodeEnv` — structural because an
      * application's Config is its own interface and need not declare it at all.
+     * The fallback signal, used only by a project that configures no environments.
      */
     config: {
         nodeEnv?: string;
     } | undefined;
+    /** `environments` from pikku.config.json, as generated beside the personas. */
+    environments?: Readonly<Record<string, PersonaEnvironment>>;
+    /** Which of them this process is. Defaults to `PIKKU_ENV`. */
+    environment?: string;
     persona: string;
     disposition?: string;
     seed?: number;
@@ -112,7 +118,7 @@ export interface StartedVirtualUserRun {
  * scheduled tick have in common. The dispatch that follows is typed off the
  * app's RPC map, so it stays in the generated wiring.
  */
-export declare const startVirtualUserRun: ({ store, personas, config, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }: StartVirtualUserRunParams) => Promise<StartedVirtualUserRun>;
+export declare const startVirtualUserRun: ({ store, personas, config, environments, environment, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }: StartVirtualUserRunParams) => Promise<StartedVirtualUserRun>;
 /**
  * One run on the wire.
  *

package/dist/wirings/virtual-user/virtual-user-scaffold.js

@@ -85,6 +85,28 @@ export const requireVirtualUserScheduleStore = (store) => {
     }
     return store;
 };
+/**
+ * Whether this process is running against production, for the disposition rule.
+ *
+ * The configured environment wins over `NODE_ENV` because they answer different
+ * questions. A deployment whose staging is a production *mirror* runs
+ * `NODE_ENV=production` there too — keying on it refuses every disposition on
+ * the one environment they exist to be used on. `PIKKU_ENV` names which of the
+ * configured environments this is, which is the question actually being asked,
+ * and it is the same signal `personaEnvironmentRefusal` already checks at
+ * sign-in.
+ *
+ * Unresolved is treated as production: an environment nobody can name is one
+ * whose data nobody can vouch for. `NODE_ENV` remains the answer only for a
+ * project that configures no environments at all, which has no production
+ * environment declared for this to be wrong about.
+ */
+const isProductionRun = (config, environments, environment) => {
+    if (!environments || Object.keys(environments).length === 0) {
+        return config?.nodeEnv === 'production';
+    }
+    return environment ? Boolean(environments[environment]?.production) : true;
+};
 /**
  * Resolves a request against the declaration and records the run.
  *
@@ -92,7 +114,7 @@ export const requireVirtualUserScheduleStore = (store) => {
  * scheduled tick have in common. The dispatch that follows is typed off the
  * app's RPC map, so it stays in the generated wiring.
  */
-export const startVirtualUserRun = async ({ store, personas, config, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
+export const startVirtualUserRun = async ({ store, personas, config, environments, environment = process.env.PIKKU_ENV, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
     const runStore = requireVirtualUserRunStore(store);
     const persona = runnablePersona(personas, personaId);
     const disposition = (requested ??
@@ -101,8 +123,8 @@ export const startVirtualUserRun = async ({ store, personas, config, persona: pe
     // Every disposition other than this one exists to find out what the product
     // does wrong, which is not a thing to do to real customers' data. Checked
     // against the effective disposition, so an override cannot smuggle one in.
-    if (config?.nodeEnv === 'production' &&
-        disposition !== PRODUCTION_DISPOSITION) {
+    if (disposition !== PRODUCTION_DISPOSITION &&
+        isProductionRun(config, environments, environment)) {
         throw new Error(`Only the '${PRODUCTION_DISPOSITION}' disposition may run against production; "${personaId}" is ${disposition}`);
     }
     // Seeded here rather than inside the engine so the record carries the seed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.96",
+  "version": "0.12.98",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/classification/data-classification.ts

@@ -54,6 +54,16 @@ export interface ColumnClassification {
   anonymize_strategy: AnonymizeStrategy
   /** At-rest representation. Absent means `plain`. */
   form?: ColumnForm
+  /**
+   * Which key protects this column, for a `wrapped` or `sealed` form. Absent
+   * means the deployment's default key.
+   *
+   * It is a purpose, not a tenant: naming one here says "these columns open
+   * together and separately from the rest", so the key that opens notes need
+   * not open credentials. The id is stored in the value, so a column that
+   * changes key is a rewrap rather than a migration.
+   */
+  keyId?: string
   description?: string
 }
 

package/src/classification/index.ts

@@ -36,3 +36,5 @@ export {
   isSecretValue,
 } from './secret-value.js'
 export type { Safe } from './secret-value.js'
+
+export { DEFAULT_KEY_ID } from './key-ids.js'

package/src/classification/key-ids.ts

@@ -0,0 +1,2 @@
+/** The key a column protects itself with when it names none. */
+export const DEFAULT_KEY_ID = 'default'

package/src/middleware/index.ts

@@ -3,10 +3,10 @@ export { authCookie } from './auth-cookie.js'
 export { authBearer } from './auth-bearer.js'
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js'
 export { cors } from './cors.js'
+export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js'
 export { telemetryOuter, telemetryInner } from './telemetry.js'
 export {
   addTagMiddleware,
-  addTagMiddleware as addMiddleware,
   addGlobalMiddleware,
   runMiddleware,
 } from '../middleware-runner.js'

package/src/middleware/require-origin.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js'
+import { InvalidOriginError } from '../errors/errors.js'
+import { resetPikkuState } from '../pikku-state.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const headers = (values: Record<string, string | undefined>) => ({
+  method: () => 'post',
+  header: (name: string) => values[name],
+})
+
+const run = async (
+  config: Parameters<typeof requireOrigin>[0],
+  values: Record<string, string | undefined>
+) => {
+  let reached = false
+  const middleware = requireOrigin(config)
+  await middleware({} as any, { http: { request: headers(values) } } as any, async () => {
+    reached = true
+  })
+  return reached
+}
+
+describe('toOrigin', () => {
+  test('keeps scheme, host and port and drops the rest', () => {
+    assert.equal(toOrigin('https://app.com:8443/a/b?c=1'), 'https://app.com:8443')
+  })
+
+  test('rejects the sandboxed-iframe "null" origin and unparseable values', () => {
+    assert.equal(toOrigin('null'), null)
+    assert.equal(toOrigin(''), null)
+    assert.equal(toOrigin(undefined), null)
+  })
+})
+
+describe('isAllowedOrigin', () => {
+  test('matches the request host exactly', () => {
+    assert.equal(isAllowedOrigin('https://app.com', 'https://app.com', []), true)
+  })
+
+  test('does not suffix-match a lookalike domain', () => {
+    assert.equal(isAllowedOrigin('https://evil-app.com', null, ['https://app.com']), false)
+    assert.equal(isAllowedOrigin('https://app.com.evil.net', null, ['https://app.com']), false)
+  })
+
+  test('normalises a configured origin before comparing', () => {
+    assert.equal(isAllowedOrigin('https://app.com', null, ['https://app.com/path']), true)
+  })
+
+  test('rejects a missing origin', () => {
+    assert.equal(isAllowedOrigin(null, 'https://app.com', ['https://app.com']), false)
+  })
+})
+
+describe('requireOrigin', () => {
+  test('allows a beacon from the request own host', async () => {
+    assert.equal(
+      await run({}, { origin: 'https://app.com', host: 'app.com' }),
+      true
+    )
+  })
+
+  test('falls back to referer when only it is sent', async () => {
+    assert.equal(
+      await run({}, { referer: 'https://app.com/pricing', host: 'app.com' }),
+      true
+    )
+  })
+
+  test('honours x-forwarded-proto when deriving the host origin', async () => {
+    assert.equal(
+      await run(
+        {},
+        { origin: 'http://app.com', host: 'app.com', 'x-forwarded-proto': 'http' }
+      ),
+      true
+    )
+  })
+
+  test('rejects another site with a 403', async () => {
+    await assert.rejects(
+      () => run({}, { origin: 'https://evil.com', host: 'app.com' }),
+      InvalidOriginError
+    )
+  })
+
+  test('rejects a non-browser caller that sends no origin', async () => {
+    await assert.rejects(
+      () => run({}, { host: 'app.com' }),
+      InvalidOriginError
+    )
+  })
+
+  test('resolves configured origins from services when given a function', async () => {
+    assert.equal(
+      await run(
+        { origins: async () => ['https://other.com'] },
+        { origin: 'https://other.com', host: 'app.com' }
+      ),
+      true
+    )
+  })
+
+  test('passes through when there is no http wire at all', async () => {
+    let reached = false
+    await requireOrigin({})({} as any, {} as any, async () => {
+      reached = true
+    })
+    assert.equal(reached, true)
+  })
+})

package/src/middleware/require-origin.ts

@@ -0,0 +1,79 @@
+import type { CoreSingletonServices } from '../types/core.types.js'
+import { InvalidOriginError } from '../errors/errors.js'
+import {
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './middleware-factories.js'
+
+/** Scheme + host + port, or null for anything unparseable including the literal `"null"` origin. */
+export const toOrigin = (value: string | null | undefined): string | null => {
+  if (!value) return null
+  try {
+    const url = new URL(value)
+    return url.protocol && url.host ? url.origin : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Whether a request origin may post to an origin-locked route.
+ *
+ * The comparison is exact on the parsed origin, never a suffix match:
+ * `endsWith('myapp.com')` also accepts `https://evil-myapp.com`.
+ */
+export const isAllowedOrigin = (
+  requestOrigin: string | null,
+  hostOrigin: string | null,
+  configuredOrigins: string[]
+): boolean => {
+  if (!requestOrigin) return false
+  if (hostOrigin && requestOrigin === hostOrigin) return true
+  return configuredOrigins.some((allowed) => toOrigin(allowed) === requestOrigin)
+}
+
+/**
+ * Rejects a request with a 403 unless its `Origin` is this app's own or explicitly allowed.
+ *
+ * This is not what `cors()` does. CORS sets response headers and is enforced by the
+ * browser, so a non-browser client ignores them and the request still runs; this rejects
+ * before the function body. It stops another site's page from posting to an unauthed
+ * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
+ * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ */
+export const requireOrigin = pikkuMiddlewareFactory<{
+  /** Extra allowed origins beyond the request's own host, or a resolver for them. */
+  origins?:
+    | string[]
+    | ((services: CoreSingletonServices) => string[] | Promise<string[]>)
+}>(({ origins = [] } = {}) =>
+  pikkuMiddleware({
+    name: 'requireOrigin',
+    description: 'Rejects requests that did not come from this app.',
+    func: async (services, { http }, next) => {
+      const request = http?.request
+      if (!request) return next()
+
+      const requestOrigin =
+        toOrigin(request.header('origin')) ??
+        toOrigin(request.header('referer'))
+
+      const host = request.header('host')
+      const proto = request.header('x-forwarded-proto') ?? 'https'
+      const hostOrigin = host ? toOrigin(`${proto}://${host}`) : null
+
+      const configured =
+        typeof origins === 'function'
+          ? await origins(services as CoreSingletonServices)
+          : origins
+
+      if (!isAllowedOrigin(requestOrigin, hostOrigin, configured)) {
+        throw new InvalidOriginError(
+          `Rejected origin ${requestOrigin ?? '(none)'}`
+        )
+      }
+
+      return next()
+    },
+  })
+)

package/src/public-surface.json

@@ -4,21 +4,23 @@
   "./middleware": [
     "addGlobalMiddleware",
     "addGlobalPermission",
-    "addMiddleware",
     "addTagMiddleware",
     "authAPIKey",
     "authBearer",
     "authCookie",
     "cors",
+    "isAllowedOrigin",
     "pikkuAgentMiddleware",
     "pikkuChannelMiddleware",
     "pikkuChannelMiddlewareFactory",
     "pikkuMiddleware",
     "pikkuMiddlewareFactory",
     "pikkuRemoteAuthMiddleware",
+    "requireOrigin",
     "runMiddleware",
     "telemetryInner",
-    "telemetryOuter"
+    "telemetryOuter",
+    "toOrigin"
   ],
   "./function": [
     "AbandonedError",
@@ -451,6 +453,7 @@
     "setSingletonServices"
   ],
   "./classification": [
+    "DEFAULT_KEY_ID",
     "REDACTED",
     "SecretCoercionError",
     "SecretValue",

package/src/services/secret-service.ts

@@ -4,6 +4,11 @@ import type { SecretValue } from '../classification/secret-value.js'
 export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }
 
 export interface SecretService {
+  /**
+   * Throws if the secret is not found, unless `defineSecret` declared it
+   * `optional` — then absence resolves `undefined`. Unwrap the result with
+   * `.reveal()`.
+   */
   getSecret<T = string>(key: string): Promise<SecretValue<T>>
   /** Answers for any key, including a disallowed one — it must not throw. */
   hasSecret(key: string): Promise<boolean>

package/src/services/typed-variables-service.test.ts

@@ -2,6 +2,7 @@ import { describe, test } from 'node:test'
 import assert from 'node:assert'
 import { TypedVariablesService } from './typed-variables-service.js'
 import { LocalVariablesService } from './local-variables.js'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 describe('TypedVariablesService', () => {
   const createService = (vars: Record<string, string | undefined> = {}) => {
@@ -71,3 +72,95 @@ describe('TypedVariablesService', () => {
     assert.strictEqual(missing.length, 0)
   })
 })
+
+/**
+ * Stands in for `z.enum([...]).default(...)`: a schema that answers `undefined`
+ * with a value rather than an issue. Core declares no schema library of its
+ * own, so the contract under test is Standard Schema's, not Zod's.
+ */
+const withDefault = <T>(value: T): StandardSchemaV1<unknown, T> => ({
+  '~standard': {
+    version: 1,
+    vendor: 'test',
+    validate: (input: unknown) =>
+      input === undefined ? { value } : { value: input as T },
+  },
+})
+
+const noDefault: StandardSchemaV1<unknown, string> = {
+  '~standard': {
+    version: 1,
+    vendor: 'test',
+    validate: (input: unknown) =>
+      typeof input === 'string'
+        ? { value: input }
+        : { issues: [{ message: 'expected a string' }] },
+  },
+}
+
+describe('TypedVariablesService schema defaults', () => {
+  const createService = (vars: Record<string, string | undefined> = {}) =>
+    new TypedVariablesService(new LocalVariablesService(vars), {
+      GITHUB_BASE_URL: {
+        name: 'GITHUB_BASE_URL',
+        displayName: 'GitHub Base URL',
+        schema: withDefault('https://api.github.com'),
+      },
+      API_KEY: {
+        name: 'API_KEY',
+        displayName: 'API Key',
+        schema: noDefault,
+      },
+      // The form code generation emits, deferred past the import cycle.
+      REGION: {
+        name: 'REGION',
+        displayName: 'Region',
+        schema: () => withDefault('eu-west-1'),
+      },
+    })
+
+  test('resolves a declared default when the host sets nothing', async () => {
+    const service = createService()
+    assert.strictEqual(
+      await service.get('GITHUB_BASE_URL'),
+      'https://api.github.com'
+    )
+  })
+
+  test('prefers the host value over the default', async () => {
+    const service = createService({ GITHUB_BASE_URL: 'https://ghe.internal' })
+    assert.strictEqual(
+      await service.get('GITHUB_BASE_URL'),
+      'https://ghe.internal'
+    )
+  })
+
+  test('stays undefined when the schema carries no default', async () => {
+    const service = createService()
+    assert.strictEqual(await service.get('API_KEY'), undefined)
+  })
+
+  test('resolves a default behind a thunk', async () => {
+    const service = createService()
+    assert.strictEqual(await service.get('REGION'), 'eu-west-1')
+  })
+
+  test('a defaulted variable is not missing', async () => {
+    const service = createService()
+    const missing = await service.getMissing()
+    assert.deepStrictEqual(
+      missing.map((v) => v.variableId),
+      ['API_KEY']
+    )
+  })
+
+  test('status separates having a default from being configured', async () => {
+    const service = createService()
+    const status = await service.getAllStatus()
+    const github = status.find((s) => s.variableId === 'GITHUB_BASE_URL')!
+    assert.strictEqual(github.isConfigured, false)
+    assert.strictEqual(github.hasDefault, true)
+    const apiKey = status.find((s) => s.variableId === 'API_KEY')!
+    assert.strictEqual(apiKey.hasDefault, false)
+  })
+})