@pikku/inspector 0.12.52 → 0.12.55

package/CHANGELOG.md

@@ -1,3 +1,344 @@
+## 0.12.55
+
+### Patch Changes
+
+- ae4e898: Carry a secret's `allowedHosts` through code generation, and close three gaps in
+  the SSRF guard.
+
+  `allowedHosts` was declared and enforced but never survived codegen: the
+  inspector did not read the property off the `defineSecret` literal, and the meta
+  builder rebuilt its objects without it. Enforcement in `assertSecretAllowedForHost`
+  then always saw `undefined`, so the egress restriction was a no-op by default —
+  and, with `secrets.requireAllowedHosts` set, threw for every secret including the
+  ones that correctly declared hosts. Both stages now carry the field, and the
+  secrets verifier asserts it against the generated JSON rather than a hand-written
+  meta literal, which is why the existing tests stayed green.
+
+  `isPrivateHost` now checks an explicit CIDR table instead of ad-hoc octet
+  comparisons. It previously missed `100.64.0.0/10` — which contains Alibaba
+  Cloud's `100.100.100.200` metadata endpoint — along with `192.0.0.0/24`,
+  `198.18.0.0/15`, `192.88.99.0/24`, the TEST-NETs, multicast and reserved space.
+  IPv6 gains a real parser, so `fec0::/10`, `ff00::/8`, and NAT64 (`64:ff9b::/96`)
+  and 6to4 (`2002::/16`) forms wrapping an internal IPv4 address are caught.
+
+  `safeFetch` takes an optional `resolveHost`, checked on the initial URL and every
+  redirect hop, so a _public_ hostname pointing at a private address is refused —
+  the `169-254-169-254.nip.io` shape a literal-only check cannot see. Core cannot
+  resolve DNS itself (Workers has no DNS API), so the Node resolver ships as
+  `@pikku/core/node-host-resolver` and the Node server runtimes install it during
+  `init()`. The connection is not pinned to the address that was checked, so a
+  rebind between check and connect is still possible.
+
+  The graph addon's `httpRequest` node called bare `fetch`, bypassing the guard
+  entirely; it now goes through `safeFetch`.
+
+- Updated dependencies [e848eb2]
+- Updated dependencies [b170489]
+- Updated dependencies [ae4e898]
+  - @pikku/core@0.12.79
+
+## 0.12.54
+
+### Patch Changes
+
+- 62ea4cc: The audit trail is now readable — in the generated meta, through an RPC, and as
+  a page in the console.
+
+  `audit: true` reaches `FunctionRuntimeMeta.audit` as its resolved form
+  (`{ durability }`), so which functions record anything is answerable without
+  running them. It is informational: the runner still resolves audit from the live
+  function config, so meta and runtime cannot disagree.
+
+  `AuditService` grows an optional read side — `query(AuditQuery)` and `facets()`.
+  Optional because a sink can legitimately be write-only: a queue producer that
+  hands events to another system has nothing to read back, and a reader that finds
+  these absent should say the trail is not readable here rather than that it is
+  empty. The two are very different answers to give someone auditing a system.
+
+  `KyselyAuditService` implements both, newest first with offset paging, filtered
+  by user, action and time window. Two things it now gets right that are easy to
+  get wrong: an empty filter array means "match nothing" rather than "no filter",
+  and results are read by physical _and_ camelCase key, because `CamelCasePlugin`
+  is on most pikku Kysely instances and renames result keys on the way out — the
+  mismatch does not throw, it returns a page of `undefined`. `init()` creates the
+  `audit` table for projects that do not migrate it themselves, from a new
+  exported `auditSchema` that stays out of `pikkuSchemas` because the runtime does
+  not need it.
+
+  The console addon exposes `console:getAudits` and `console:getAuditFilters`
+  behind a new `pikku:audit:read` scope, and forwards the application's `audit`
+  service into the addon's own services — without that last part every install
+  reported the trail as unreadable, whatever sink it had configured.
+
+  The console gets an Audit trail page: an infinite list filtered server-side by
+  user and action, and a row that opens the whole event, metadata rendered as a
+  JSON tree. Refused, unreadable and empty are three different screens, because
+  "you may not read this", "nobody can read this" and "nothing happened" are three
+  different facts.
+
+  Events name the person who caused them. The trail records a user id — the only
+  thing stable enough to record, since a name can change after the event — so
+  `getAudits` resolves those ids against better-auth's user directory at read
+  time, and the page shows the name while keeping the recorded id on the event.
+  The filter follows: pick a colleague by name, filter by the id. A scenario
+  actor is labelled as one, so synthetic traffic is not mistaken for real, and a
+  caller who was signed out shows the wire identity pikku resolved for them
+  rather than being credited to the system.
+
+  **Breaking, for anyone already reading `AuditEvent`:** `actor` is now
+  `userIdentity`, and its type `AuditActor` is `AuditUserIdentity`; `AuditQuery`
+  takes `userIds`/`orgId` in place of `actorUserIds`/`actorOrgId`, and
+  `AuditFacets` returns `userIds`. In pikku an _actor_ is a synthetic person a
+  scenario drives, flagged on the user row — so naming the causer of an event
+  `actor` made the synthetic case unsayable (`actor.actor === true`) and implied
+  every recorded action was a test. The overwhelming majority are ordinary
+  customers. The `audit` table follows: `actor_user_id` / `actor_org_id`
+  are now `user_id` / `org_id`, and a `pikku_user_id` column joins them so the
+  wire identity of a caller who never signed in survives the round trip — the
+  sink was dropping it, which left the console's Session field permanently
+  blank. A project that already migrated the table needs to rename the two
+  columns and add the third; `KyselyAuditService.init()` creates the new shape
+  for anyone who did not.
+
+- 9dddff8: Split a column's at-rest form out of its classification.
+
+  `security: 'encrypted'` sat beside `'secret'` as though the two were
+  alternatives, which made the field unanswerable: a token hash and a live bearer
+  token are both secret, one must never be encrypted — the digest _is_ the lookup
+  key — and the other must always be. A column now carries a second, independent
+  `form: 'plain' | 'hashed' | 'wrapped' | 'sealed'` saying how the bytes are held.
+
+  Declaring a form other than `plain` makes the column's INSERT/UPDATE type
+  nominal — `WrappedValue`, `SealedValue`, `HashedValue` — so a plain string no
+  longer compiles there and the only way to write the column is with something an
+  encrypt, seal or hash call produced. `envelopeEncrypt`, `envelopeRewrap` and
+  `wrapDEK` now return the brand, and a new `hashToken` produces `HashedValue`, so
+  the round trip needs no casts; `column-form.ts` exports deliberately-named
+  `unsafeAs*` assertions for backfills, fixtures and values sealed elsewhere.
+  Reads are unaffected — the brands widen to `string` and compose with the
+  classification brand as `Secret<WrappedValue>`.
+
+  `wrapped` and `sealed` stay distinct because a sealed value is one the
+  application cannot read back; storing one where the other belongs is a row
+  nobody can open.
+
+  A `secret` column that has not declared a form now warns (PKU483), and a form on
+  a non-text column warns and is dropped (PKU484). Both are warnings, so existing
+  projects keep migrating — `pikku db --fail-on-warn` opts into the ratchet, and
+  an explicit `form: 'plain'` is the acknowledgement that silences it. The legacy
+  `security: 'encrypted'` keeps working and now expands to the pair it always
+  meant, `secret` + `wrapped`.
+
+- 9dddff8: Read schema-qualified annotations, and let a project name its default schema.
+
+  `DbClassificationMap` nests tables under their schema whenever a project sets
+  `db.schema`, but `loadAnnotations` read the sidecar as a flat table→column map.
+  It therefore took the schema for a table and each table for a column, found no
+  recognised fields, and dropped every annotation on the floor — so a project
+  could mark a column `secret` and watch it generate as `private`, with no error
+  anywhere. The parser now detects the extra level (a column entry's values are
+  primitives; a table's are objects) and flattens it, so both shapes load.
+
+  New `db.defaultSchema` drops one schema's qualifier from the generated types:
+  with `defaultSchema: 'app'`, `app.user` is queried as `selectFrom('user')` and
+  typed as `User` rather than `AppUser`, matching what a project whose
+  `search_path` already resolves the schema actually writes. Tables in other
+  schemas stay qualified. Where dropping the qualifier would make two tables
+  share a name, the table keeps its qualifier and the codegen warns (PKU485)
+  rather than letting one silently shadow the other — queries against the loser
+  would have typechecked against the wrong columns.
+
+  The generated key is what Kysely puts in the SQL, so this is opt-in and
+  separate from `db.schema`: setting it for a schema the connection does not
+  resolve gives you queries that compile and then fail to find their table.
+
+- 155528a: The PKU910 sessionless-output diagnostic advised marking a column `@public`, a
+  SQL-comment annotation syntax that no longer exists. Column classification is
+  sourced solely from the hand-authored `db/annotations.ts`, so the message now
+  points there.
+- 78b29f0: `SecretService` now returns a `SecretValue<T>` rather than the bare value, so a
+  vault secret cannot reach a sink by accident.
+
+  `SecretValue` is nominally typed, which means it is not assignable to `string`
+  (or to any other concretely-typed field). Every sink with a real type — a
+  database column, an email body, a session payload — rejects it with no lint
+  rule involved. The sinks typed `any`, `unknown`, or a free generic — the logger,
+  queue payloads, webhook and email inputs, and a function's own output — are
+  guarded with `Safe<T>`, which collapses a `SecretValue` found anywhere inside
+  `T`, however deeply nested, to `never`.
+
+  Unwrap deliberately at the point the secret reaches the wire:
+
+  ```ts
+  const secret = await secrets.getSecret('BETTER_AUTH_SECRET')
+  betterAuth({ secret: secret.reveal() })
+  ```
+
+  Two behaviours cover what types cannot see. Structured serialization redacts —
+  `JSON.stringify` and node's inspect both yield `[secret]`, so an audit or log
+  write stays honest without crashing the request. String coercion throws
+  `SecretCoercionError`, because a template literal is always a leak.
+
+  `AuditLog.write` is guarded the same way as the logger, since an audit event
+  carries `input` and `metadata` as `unknown` and nominality alone cannot stop a
+  secret landing in one.
+
+  `.reveal()` is the deliberate escape hatch, and what it hands back is an
+  ordinary string as far as every sink signature is concerned. **PKU953** closes
+  that gap: under `pikku all --security` the inspector reports a revealed secret
+  that flows into a logger, an audit, a queue, an email or a webhook — `console` included.
+
+  This also fixed a real one: `remote-addon-auth.ts` called `String(token)` on an
+  `unknown` and wrote the result straight into an `Authorization` header.
+
+- Updated dependencies [62ea4cc]
+- Updated dependencies [9dddff8]
+- Updated dependencies [78b29f0]
+  - @pikku/core@0.12.76
+
+## 0.12.53
+
+### Patch Changes
+
+- fd72e58: Drop `scenario.step` — a scenario step is now always a `given`, `when` or
+  `then`.
+
+  `step` rendered no keyword, which made it the phase to reach for whenever a
+  step did not obviously fit one of the three. That is exactly the step a reader
+  cannot check: a scenario is read by people deciding whether it describes the
+  behaviour they wanted, and a row that says what it does without saying whether
+  it is setup, action or claim tells them nothing to agree or disagree with. It
+  was also the escape hatch from the assertion lint — a scenario with no `then`
+  could be made to stop complaining by demoting its steps rather than by
+  asserting anything.
+
+  Replace `scenario.step(...)` with whichever of `given`, `when` or `then` the
+  step actually is. `then` is not a rename: it makes the step's bindings
+  witnesses rather than alternatives, so every declared surface runs and they
+  must agree.
+
+- d041d5b: Let a generated file declare scopes, roles and personas without taking the
+  single-declaration slot.
+
+  `defineScope`, `defineSystemRole` and `definePersonas` are one-per-codebase, and
+  the CLI generates declarations of its own — `user-admin.gen.ts` ships the whole
+  `admin` scope tree. Any project that scaffolded one therefore had two
+  declarations and failed codegen with PKU583, and the losing file's scopes were
+  dropped from the metadata rather than merged.
+
+  The rule exists to name the one place a person reads from and adds to, and
+  nobody adds to a file the next codegen run overwrites. A generated declaration
+  is still extracted; it just neither claims the slot nor collides with the app's
+  own.
+
+- fd72e58: Make personas a first-class surface rather than a detail of the test runner.
+
+  A persona is now read in three places — the knowledge base resolves `persona:`
+  URIs against it, scenarios cast it as an actor, and a virtual user runs as it —
+  so it gets its own page at `/personas` under a new **People** section in the
+  rail, alongside Users. The card is a profile: avatar, name, job title, computed
+  address, the system roles they hold, and how many scenarios cast them. Opening
+  one expands each role to the scopes it confers, which is the half of the picture
+  that explains a 403.
+
+  `definePersonas` takes an optional `avatarUrl` — any URL a browser can load.
+  Nothing is derived from the address: a persona's address is synthetic, so a
+  derived identicon would be the same shrug for everyone. Omitted, the console
+  keeps drawing the deterministic colour-and-icon avatar from the persona's id.
+
+- fd72e58: Read the actors that are not people on the personas page.
+
+  The platform — the app acting on itself, what `pikkuPlatformScenarioStep`
+  declares — now has a row of its own, alongside one per addon whose system a
+  step makes act. They sit behind a People / System / All filter that opens on
+  the people: a subject holds no roles and signs in as nobody, so leading with it
+  would put the rows nothing is authorized through above the ones that are.
+
+  The platform row is built in rather than derived. A project that has never
+  written a platform step still has a platform, and a card that appeared the
+  moment somebody declared their first step would read as a feature they had
+  switched on.
+
+  Also: PKU680 now counts `expectService`, `expectError` and `expectEventually`
+  as assertions. They are inline steps and carry no phase, so a scenario whose
+  only witness was a recorded service call was being told it never asserts.
+
+- 894b2f8: `defineScope` and `defineSystemRole` accumulate across call sites again. Only `definePersonas` is one-per-codebase.
+
+  The previous release made all three single-declaration constructs, which no project scaffolding user-admin could satisfy: the CLI generates a `defineScope` of its own in `user-admin.gen.ts` carrying the whole `admin` tree, and `@pikku/addon-console` spells the same tree out again, so a second hand-written declaration failed the build with PKU583 — and the losing file's scopes were dropped from the metadata rather than merged.
+
+  Exempting generated files would have reinstated exactly the ambiguity the rule removes, only for the files nobody can read the rule from. The real fix is for `admin` to be a default scope nobody declares, at which point the rule can come back for scopes and roles.
+
+  `definePersonas` is unaffected: nothing generates one, so its single call site stands.
+
+- dd19aa7: Drop `scopes` from sessionless functions, rename `selfAuthenticated`, and make both
+  escape hatches opt-in.
+
+  **`scopes` are gone from `pikkuSessionlessFunc`.** They are AND-ed and `verifyScopes`
+  fails closed on a session that does not exist, so every scope listed on a sessionless
+  function rejected the anonymous caller it exists to serve. `CorePikkuSessionlessFunctionConfig`
+  now states this once in core, and the generated `pikkuSessionlessFunc` / `pikkuVoidFunc`
+  configs derive from it — so the field is absent rather than subtracted.
+
+  `@pikku/addon-console`'s `installAddon` and `installOpenapiAddon` are now `pikkuFunc`.
+  Both set `auth: true` and `scopes: ['admin']`, and a test exercises that gate, so the
+  scopes were load-bearing — they only compiled as sessionless because the config accepted
+  a field it could not honour. No behaviour change: both already required a session.
+
+  **`selfAuthenticated` is now `permissionsInBody`.** It never described authentication:
+  what it records is that the permission check lives in the function body rather than in a
+  declared `permissions` entry.
+
+  **Both escape hatches must be opted into**, via a new `allow` block in
+  `pikku.config.json`:
+
+  ```json
+  "allow": { "permissionsInBody": true, "complexWorkflows": true }
+  ```
+
+  Unset means unavailable, and using the feature is a build error naming the flag that
+  would permit it — PKU576 for `permissionsInBody`, PKU643 for `pikkuWorkflowComplexFunc`.
+  Both trade something the tooling can inspect for something only a reader can verify: a
+  permission check buried in a body, or workflow steps that cannot be serialized into the
+  graph, replayed, or migrated. Both are occasionally right, and both are the path of least
+  resistance whenever the declarative form is merely inconvenient. Whoever owns the project
+  makes that call once, in writing, instead of every author making it silently at the call
+  site.
+
+  **PKU574's message no longer contradicts any of this.** Every function it reports is
+  sessionless — that is how the population is selected, not a finding — yet it opened by
+  reporting that they "require neither a session", then advised adding scopes. It now names
+  them as sessionless and recommends only gates an anonymous caller can meet:
+  `permissions`, `auth: true`, `wireAddon({ auth: true })`, or dropping `expose: true`.
+  `permissionsInBody` is deliberately absent from that list: a diagnostic should not
+  advertise its own escape hatch.
+
+- 50ec500: Make `defineScope`, `defineSystemRole` and `definePersonas` single-declaration constructs
+  — exactly one call site per codebase, the rule `pikkuBetterAuth` has always had.
+
+  Each of the three already takes a keyed object, so one call declares as many entries as
+  you like. Spreading the calls across files bought nothing and cost the thing that matters:
+  there was no answer to "where do I add a persona?", so downstream tooling and agents had
+  nowhere unambiguous to read from or append to. The only duplicate handling that existed
+  caught a narrow case — the same id declared twice with different content — and said
+  nothing about the same id declared twice in two files.
+
+  A second call now fails the build with `PKU583` (`defineScope`), `PKU584`
+  (`defineSystemRole`) or `PKU585` (`definePersonas`), naming both source files and saying
+  to declare them all in one call. A second call in the _same_ file is refused too: "the
+  file" is not an answer either when the file holds two calls.
+
+- Updated dependencies [32277d5]
+- Updated dependencies [ea8aabf]
+- Updated dependencies [33e96ab]
+- Updated dependencies [fd72e58]
+- Updated dependencies [fd72e58]
+- Updated dependencies [fd72e58]
+- Updated dependencies [894b2f8]
+- Updated dependencies [dd19aa7]
+- Updated dependencies [50ec500]
+  - @pikku/core@0.12.75
+
 ## 0.12.52
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -29,6 +29,7 @@ import { resolvePermissions } from '../utils/permissions.js';
 import { extractWireNames } from '../utils/post-process.js';
 import { ErrorCode } from '../error-codes.js';
 import { findPiiPaths } from '../utils/check-pii-output.js';
+import { findRevealedSecretSinks } from '../utils/check-secret-sinks.js';
 import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js';
 const isValidVariableName = (name) => {
     const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
@@ -403,7 +404,9 @@ export const addFunctions = (logger, node, checker, state, options) => {
      */
     let auth;
     /** The author's claim that the body authorizes its own callers. */
-    let selfAuthenticated;
+    let permissionsInBody;
+    /** The function's `audit` config, resolved to its object form. */
+    let audit;
     let readonly_;
     let deploy;
     let approvalRequired;
@@ -480,7 +483,33 @@ export const addFunctions = (logger, node, checker, state, options) => {
         remote = getPropertyValue(firstArg, 'remote');
         mcp = getPropertyValue(firstArg, 'mcp');
         auth = getPropertyValue(firstArg, 'auth');
-        selfAuthenticated = getPropertyValue(firstArg, 'selfAuthenticated');
+        permissionsInBody = getPropertyValue(firstArg, 'permissionsInBody');
+        if (permissionsInBody && !options.allow?.permissionsInBody) {
+            logger.critical(ErrorCode.PERMISSIONS_IN_BODY_NOT_ALLOWED, `'${name}' declares \`permissionsInBody: true\`, which this project has not enabled. ` +
+                `It silences the exposed-and-ungated audit without gating anything, so it is opt-in: ` +
+                `set \`allow: { permissionsInBody: true }\` in pikku.config.json if the project accepts ` +
+                `permission checks that only a reader can verify. Otherwise express the check as a ` +
+                `\`permissions\` entry, or drop \`expose: true\` if the function was not meant to be ` +
+                `callable from outside.`);
+            return;
+        }
+        // `audit` is either `true` or `{ durability }`, so it needs the nested read:
+        // getPropertyValue stringifies an object initializer rather than parsing it.
+        // Mirrors core's `resolveAuditConfig` — the two must agree, or meta would
+        // claim a durability the runner does not use.
+        const auditProp = firstArg.properties.find((p) => ts.isPropertyAssignment(p) &&
+            ts.isIdentifier(p.name) &&
+            p.name.text === 'audit');
+        if (auditProp && ts.isPropertyAssignment(auditProp)) {
+            const auditInit = auditProp.initializer;
+            if (auditInit.kind === ts.SyntaxKind.TrueKeyword) {
+                audit = { durability: 'best-effort' };
+            }
+            else if (ts.isObjectLiteralExpression(auditInit)) {
+                const durability = getPropertyValue(auditInit, 'durability');
+                audit = { durability: durability ?? 'best-effort' };
+            }
+        }
         readonly_ = getPropertyValue(firstArg, 'readonly');
         deploy = getPropertyValue(firstArg, 'deploy');
         approvalRequired = getPropertyValue(firstArg, 'approvalRequired');
@@ -847,6 +876,18 @@ export const addFunctions = (logger, node, checker, state, options) => {
     // it runs ONLY when explicitly requested (`pikku all --security`) — see the
     // classificationCheck option. Default codegen skips it entirely.
     if (options.classificationCheck) {
+        // A revealed vault secret is invisible to the return-type scan below when it
+        // is written out mid-body rather than returned, so walk the sinks too.
+        for (const violation of findRevealedSecretSinks(checker, handler)) {
+            logger.diagnostic({
+                severity: 'error',
+                code: ErrorCode.SECRET_REVEALED_INTO_SINK,
+                message: `Function '${name}' passes a revealed secret to '${violation.sink}' ` +
+                    `at line ${violation.line} (path '${violation.path}').\n  ` +
+                    `A vault secret must not be written to a log, an audit, a queue, an email or a webhook. ` +
+                    `Pass the value only to the client that needs it, and reveal it there.`,
+            });
+        }
         const sig = checker.getSignatureFromDeclaration(handler);
         if (sig) {
             const rawRet = checker.getReturnTypeOfSignature(sig);
@@ -875,7 +916,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
                     message: `Sessionless function '${name}' exposes private-classified field(s) in its return type: ` +
                         privatePaths.map((p) => `'${p}'`).join(', ') +
                         `.\n  Private fields are only safe to return from authenticated (sessioned) functions. ` +
-                        `Either require a session (use pikkuFunc) or mark the column @public if it is safe to expose publicly.`,
+                        `Either require a session (use pikkuFunc) or set the column's security to 'public' in db/annotations.ts if it is safe to expose publicly.`,
                 });
             }
         }
@@ -937,7 +978,8 @@ export const addFunctions = (logger, node, checker, state, options) => {
         outputs: outputNames.filter((n) => n !== 'void') ?? null,
         expose: expose || undefined,
         auth: auth || undefined,
-        selfAuthenticated: selfAuthenticated || undefined,
+        permissionsInBody: permissionsInBody || undefined,
+        audit,
         remote: remote || undefined,
         scenarioStep: isScenarioStep || undefined,
         scenario: isScenario || undefined,

package/dist/add/add-keyed-wiring.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { getPropertyValue, assertStringLiteralProperty, } from '../utils/get-property-value.js';
+import { getPropertyValue, getArrayPropertyValue, assertStringLiteralProperty, } from '../utils/get-property-value.js';
 import { ErrorCode } from '../error-codes.js';
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js';
 import { parseDurationString } from '@pikku/core';
@@ -27,6 +27,7 @@ export const createAddKeyedWiring = (config) => {
             const descriptionValue = getPropertyValue(obj, 'description');
             const rotationPeriodValue = getPropertyValue(obj, 'rotationPeriod');
             const docsUrlValue = getPropertyValue(obj, 'docsUrl');
+            const allowedHostsValue = getArrayPropertyValue(obj, 'allowedHosts');
             const idValue = getPropertyValue(obj, config.idField);
             let schemaVariableName = null;
             let schemaSourceFile = null;
@@ -104,6 +105,7 @@ export const createAddKeyedWiring = (config) => {
                 description: descriptionValue || undefined,
                 rotationPeriod: rotationPeriodValue || undefined,
                 docsUrl: docsUrlValue || undefined,
+                allowedHosts: allowedHostsValue || undefined,
                 [config.idField]: idValue,
                 schema: schemaLookupName,
                 sourceFile,

package/dist/add/add-personas.js

@@ -2,6 +2,7 @@ import * as ts from 'typescript';
 import { DISPOSITIONS } from '@pikku/core/virtual-user';
 import { isRunnablePersona } from '@pikku/core/persona';
 import { ErrorCode } from '../error-codes.js';
+import { claimSingleDeclaration } from '../utils/single-declaration.js';
 import { booleanProperty, getProperty, numberProperty, stringArrayProperty, stringProperty, unwrapAs, } from '../utils/literal-properties.js';
 /** A dial and the range outside which it is a mistake rather than a choice. */
 const RATES = [
@@ -123,6 +124,9 @@ export const addPersonas = (logger, node, _checker, state) => {
         return;
     }
     const sourceFile = node.getSourceFile().fileName;
+    if (!claimSingleDeclaration(logger, state.personas.files, ErrorCode.DUPLICATE_PERSONAS_DEFINITION, 'definePersonas', sourceFile)) {
+        return;
+    }
     const known = Object.keys(DISPOSITIONS);
     for (const prop of unwrapped.properties) {
         if (!ts.isPropertyAssignment(prop)) {
@@ -182,6 +186,9 @@ export const addPersonas = (logger, node, _checker, state) => {
         const description = stringProperty(config, 'description');
         if (description !== undefined)
             persona.description = description;
+        const avatarUrl = stringProperty(config, 'avatarUrl');
+        if (avatarUrl !== undefined)
+            persona.avatarUrl = avatarUrl;
         const personality = stringProperty(config, 'personality');
         if (personality !== undefined)
             persona.personality = personality;
@@ -204,7 +211,6 @@ export const addPersonas = (logger, node, _checker, state) => {
         const linkedAccounts = linkedAccountsProperty(config, id, logger);
         if (linkedAccounts !== undefined)
             persona.linkedAccounts = linkedAccounts;
-        state.personas.files.add(sourceFile);
         state.personas.definitions.push(persona);
     }
 };

package/dist/add/add-workflow.js

@@ -208,7 +208,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
  * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
  * pikkuScenario() calls. Detects workflow registration and extracts metadata.
  */
-export const addWorkflow = (logger, node, checker, state) => {
+export const addWorkflow = (logger, node, checker, state, options) => {
     if (!ts.isCallExpression(node)) {
         return;
     }
@@ -223,6 +223,14 @@ export const addWorkflow = (logger, node, checker, state) => {
         wrapperType = 'dsl';
     }
     else if (expression.text === 'pikkuWorkflowComplexFunc') {
+        if (!options.allow?.complexWorkflows) {
+            logger.critical(ErrorCode.COMPLEX_WORKFLOW_NOT_ALLOWED, `'${expression.text}' is used here, but this project has not enabled complex workflows. ` +
+                `Their inline steps cannot be serialized, so they are absent from the workflow graph and ` +
+                `cannot be replayed or migrated across a definition change. Express the workflow with ` +
+                `pikkuWorkflowFunc and the step DSL, or set \`allow: { complexWorkflows: true }\` in ` +
+                `pikku.config.json if the project accepts that trade.`);
+            return;
+        }
         wrapperType = 'complex';
     }
     else if (expression.text === 'pikkuScenario') {
@@ -292,6 +300,7 @@ export const addWorkflow = (logger, node, checker, state) => {
     let steps = [];
     let context = undefined;
     let dsl = undefined;
+    let asserts = undefined;
     // Try DSL workflow extraction first
     // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
     const result = extractDSLWorkflow(node, checker, {
@@ -301,6 +310,7 @@ export const addWorkflow = (logger, node, checker, state) => {
         // Extraction succeeded
         steps = result.steps;
         context = result.context;
+        asserts = result.asserts;
         // Check if workflow contains inline steps (non-serializable)
         if (hasInlineSteps(steps)) {
             if (wrapperType === 'dsl') {
@@ -374,6 +384,7 @@ export const addWorkflow = (logger, node, checker, state) => {
         expose,
         skip,
         scenario: wrapperType === 'scenario' ? true : undefined,
+        asserts,
         actors: actorNames.length > 0 ? actorNames : undefined,
     };
     // The scenario "logger/config only" rule (PKU673) and the implicit

package/dist/error-codes.d.ts

@@ -27,21 +27,27 @@ export declare enum ErrorCode {
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",
     WORKFLOW_GRAPH_ADDON_NOT_WIRED = "PKU642",
+    COMPLEX_WORKFLOW_NOT_ALLOWED = "PKU643",
     REMOTE_ADDON_NOT_DEV_DEPENDENCY = "PKU338",
     REMOTE_ADDON_AUTH_UNRESOLVED = "PKU339",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
+    DB_SECRET_COLUMN_STORED_PLAIN = "PKU483",
+    DB_FORM_ON_NON_STRING = "PKU484",
+    DB_DEFAULT_SCHEMA_NAME_COLLISION = "PKU485",
     SCHEMA_GENERATION_ERROR = "PKU456",
     INLINE_SCHEMA = "PKU489",
     FUNCTION_METADATA_NOT_FOUND = "PKU559",
     DUPLICATE_AUTH_DEFINITION = "PKU581",
     AUTH_NOT_EXPORTED = "PKU582",
+    DUPLICATE_PERSONAS_DEFINITION = "PKU585",
     ROUTE_PARAM_MISMATCH = "PKU571",
     ROUTE_QUERY_MISMATCH = "PKU572",
     AUTH_DISABLED_REQUIRES_SESSIONLESS = "PKU573",
     EXPOSED_FUNCTION_HAS_NO_GATE = "PKU574",
     TAG_RESOLVES_TO_NO_MIDDLEWARE = "PKU575",
+    PERMISSIONS_IN_BODY_NOT_ALLOWED = "PKU576",
     DUPLICATE_FUNCTION_VERSION = "PKU850",
     DUPLICATE_FUNCTION_NAME = "PKU851",
     MANIFEST_MISSING = "PKU860",
@@ -67,7 +73,8 @@ export declare enum ErrorCode {
     RPC_INVOCATION_TYPE_CAST = "PKU940",
     SECRET_SERVICE_ALIASED = "PKU950",
     SECRET_NOT_DECLARED = "PKU951",
-    SECRET_KEY_NOT_STATIC = "PKU952"
+    SECRET_KEY_NOT_STATIC = "PKU952",
+    SECRET_REVEALED_INTO_SINK = "PKU953"
 }
 /**
  * Severity of a tracked, coded diagnostic. `critical` always blocks the build;

package/dist/error-codes.js

@@ -29,6 +29,7 @@ export var ErrorCode;
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";
     ErrorCode["WORKFLOW_GRAPH_ADDON_NOT_WIRED"] = "PKU642";
+    ErrorCode["COMPLEX_WORKFLOW_NOT_ALLOWED"] = "PKU643";
     // Remote addon (wireRemoteAddon) validation
     ErrorCode["REMOTE_ADDON_NOT_DEV_DEPENDENCY"] = "PKU338";
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
@@ -36,6 +37,9 @@ export var ErrorCode;
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
     ErrorCode["DB_FORMAT_ON_NON_STRING"] = "PKU482";
+    ErrorCode["DB_SECRET_COLUMN_STORED_PLAIN"] = "PKU483";
+    ErrorCode["DB_FORM_ON_NON_STRING"] = "PKU484";
+    ErrorCode["DB_DEFAULT_SCHEMA_NAME_COLLISION"] = "PKU485";
     // Configuration errors
     ErrorCode["SCHEMA_GENERATION_ERROR"] = "PKU456";
     ErrorCode["INLINE_SCHEMA"] = "PKU489";
@@ -44,12 +48,19 @@ export var ErrorCode;
     // Auth errors
     ErrorCode["DUPLICATE_AUTH_DEFINITION"] = "PKU581";
     ErrorCode["AUTH_NOT_EXPORTED"] = "PKU582";
+    // Single-declaration constructs — one call site per codebase.
+    // PKU583 (defineScope) and PKU584 (defineSystemRole) are retired, not free:
+    // scopes and roles held this rule until the generated `admin` tree made it
+    // unsatisfiable, and get it back once `admin` is a default scope nobody
+    // declares. Do not reuse those two numbers for anything else.
+    ErrorCode["DUPLICATE_PERSONAS_DEFINITION"] = "PKU585";
     // HTTP Route errors
     ErrorCode["ROUTE_PARAM_MISMATCH"] = "PKU571";
     ErrorCode["ROUTE_QUERY_MISMATCH"] = "PKU572";
     ErrorCode["AUTH_DISABLED_REQUIRES_SESSIONLESS"] = "PKU573";
     ErrorCode["EXPOSED_FUNCTION_HAS_NO_GATE"] = "PKU574";
     ErrorCode["TAG_RESOLVES_TO_NO_MIDDLEWARE"] = "PKU575";
+    ErrorCode["PERMISSIONS_IN_BODY_NOT_ALLOWED"] = "PKU576";
     // Versioning errors
     ErrorCode["DUPLICATE_FUNCTION_VERSION"] = "PKU850";
     ErrorCode["DUPLICATE_FUNCTION_NAME"] = "PKU851";
@@ -86,4 +97,5 @@ export var ErrorCode;
     ErrorCode["SECRET_SERVICE_ALIASED"] = "PKU950";
     ErrorCode["SECRET_NOT_DECLARED"] = "PKU951";
     ErrorCode["SECRET_KEY_NOT_STATIC"] = "PKU952";
+    ErrorCode["SECRET_REVEALED_INTO_SINK"] = "PKU953";
 })(ErrorCode || (ErrorCode = {}));

package/dist/types.d.ts

@@ -268,6 +268,15 @@ export type InspectorOptions = Partial<{
      * function, which is expensive. Enabled via `pikku all --security`.
      */
     classificationCheck: boolean;
+    /**
+     * Escape hatches the project has opted into, from `allow` in
+     * `pikku.config.json`. Absent or false means the feature is refused with a
+     * critical naming the flag that would permit it.
+     */
+    allow: Partial<{
+        permissionsInBody: boolean;
+        complexWorkflows: boolean;
+    }>;
 }>;
 export interface InspectorLogger {
     info: (message: string) => void;