@pikku/core 0.12.74 → 0.12.78

package/CHANGELOG.md

@@ -1,3 +1,400 @@
+## 0.12.78
+
+### Patch Changes
+
+- f5ce870: Recover workflow runs stalled by a crash mid-dispatch.
+
+  Arming a step is two writes to two systems — the step row, then the queue or
+  scheduler job — so a process that died between them left a run `running` with
+  nothing in flight. It parked on a step that would never complete and never
+  error, so the run neither finished nor failed, and nothing swept it up.
+
+  `workflowService.recoverStalledRuns()` re-drives those runs through
+  `resumeWorkflow`. Replay is memoized per step, so resuming a run that was not
+  actually stuck changes nothing; runs mid-sleep or with a step in flight are
+  excluded outright. It is not self-starting — call it from a scheduled task.
+
+  Stores opt in by overriding `findStalledRunIds`; implemented here for the
+  Kysely and in-memory services, and a no-op elsewhere.
+
+## 0.12.77
+
+### Patch Changes
+
+- 3df4f95: Scaffold virtual user runs as RPCs, backed by a run store.
+
+  `pikku persona run` could already turn a declared persona loose on a running
+  stage, but only from a terminal, and the result only existed in that terminal's
+  output. There was no way for CI, a console, or a scheduled job to start a run —
+  and nothing kept what a run found, so this week's findings could not be compared
+  against last week's.
+
+  `scaffold.virtualUser` now generates two RPCs and the function behind them:
+  - `runVirtualUser({ persona, goals?, memory?, disposition?, budget?, seed? })
+-> { runId }`
+  - `getVirtualUserRun({ runId }) -> { status, findings, tally, memory, … }`
+
+  They are gated on separate scopes — `virtualUser:run` and `virtualUser:read` —
+  because an adversarial run's findings are working exploits carrying live ids,
+  which makes reading them the more sensitive of the two. Production refuses every
+  disposition but `accountable`, checked against the effective one so the
+  per-run override cannot smuggle another in.
+
+  **A run is not a workflow and not a queued job.** It explores, so no two
+  attempts take the same steps and there is nothing to replay; and the record
+  already carries the progress a queue would only be holding on the way to the
+  same place. `runVirtualUser` writes the record, dispatches without awaiting, and
+  returns the id. The cost is stated on the type: a restart mid-run strands a
+  record at `running`, so a run older than its budget window and still `running`
+  is dead rather than working.
+
+  `@pikku/core` gains `VirtualUserRunStore` (with `virtualUserRunStore` on
+  `CoreSingletonServices`), and `@pikku/kysely` ships
+  `KyselyVirtualUserRunStore`, which creates its own table on first use like the
+  audit sink — the runtime never needs it, so it arrives with the feature that
+  fills it rather than in every database.
+
+  Also in core: `prepareVirtualUserRun`, which derives the catalogue, intents,
+  scopes and reachable agents in one place. `pikku persona run` reads the
+  inspector state and the generated RPC reads `metaService`, and the two have to
+  agree — otherwise the same persona and seed explore a different API depending on
+  how the run was started. `personaScopes` moved here from the CLI for the same
+  reason and is still re-exported from its old home. `PRODUCTION_DISPOSITION` is
+  now exported from `@pikku/core/virtual-user`, which it should always have been.
+
+## 0.12.76
+
+### 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`.
+
+- 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.
+
+## 0.12.75
+
+### Patch Changes
+
+- 32277d5: Make a voice conversation with an agent something a chat surface can turn on, rather than
+  something each consumer reassembles.
+
+  The server half already worked — `voiceInput` transcribed, `voiceOutput` synthesized a
+  sentence at a time, and the AG-UI mapper forwarded the audio. What was missing was the
+  turn's own words. The client sends audio, so only the server ever knows what was said,
+  and nothing carried that back: a spoken turn rendered as an empty user bubble followed by
+  an answer to a question nobody could see, and thread history recorded the base64 audio
+  blob instead of the transcript — megabytes of unreadable data in place of the only
+  readable record of the turn.
+
+  `voiceInput` now records what it heard, the stream emits it as a `transcript` event ahead
+  of the run (the reply starts within a few hundred milliseconds, and a question that
+  appears after its answer reads as the wrong question), and it reaches the browser as
+  `pikku:transcript`. Both run paths persist the transcribed message rather than the one
+  that arrived on the wire. `audio-delta` also carries the sentence it says, which is what
+  a barge-in needs to report the part the user actually heard — a reply cut off after "I'll
+  delete the staging database and" is answered very differently depending on whether the
+  model knows the sentence never landed.
+
+  `@pikku/voice-agents` gains the two things a voice UI needs and could not get: a live
+  input level, attached to the source rather than to a detector so it keeps reading on the
+  Silero path, and the microphone list — re-readable on demand, because device labels are
+  empty until permission is granted and nothing fires when it is. `VoiceSession` also
+  learned manual turn boundaries, so push-to-talk is a mode rather than a detector fought
+  to a standstill: holding the key through a three-second pause is someone thinking, and
+  any endpointer worth having would cut them off.
+
+  `<PikkuAgentChat voice />` puts a microphone beside the send button, promotes it to
+  primary when nothing is typed, and opens an indicator with a live level bar, a device
+  picker and a hold-to-record toggle. It plays the agent's speech, and cancels the run on
+  barge-in — talking over the agent should stop the bill, not just the sound.
+
+  Opt-in, because the component cannot check the two things it depends on: the agent has to
+  be wired with `voiceInput` for the audio to be understood and `voiceOutput` for anything
+  to come back.
+
+- ea8aabf: Serve `LocalContent` uploads and signed reads under Bun.
+
+  `LocalContent` hands the browser a `PUT <uploadUrlPrefix>/<key>` upload URL and a signed
+  `GET <assetUrlPrefix>/<key>` read URL, but it is a `ContentService` and cannot answer
+  either — something in the serving path has to. Only `@pikku/node-http-server` did. The
+  same project served under Bun handed out upload URLs that 404ed, with nothing naming the
+  cause: the config was accepted, the service was constructed, and the URLs looked right.
+
+  `@pikku/core` now exports `createLocalContentRequestHandler` from
+  `@pikku/core/services/local-content-request-handler` — the server half of `LocalContent`,
+  expressed in Web `Request`/`Response` so every runtime shares one implementation of the
+  signature check rather than each re-deriving it. It returns `null` for anything that is
+  not a content request, which is the caller's signal to carry on with its normal routing.
+
+  `PikkuBunServer` accepts `config.content` and a `contentSigningJWT` option, mirroring
+  `PikkuNodeHTTPServer`, and answers both prefixes ahead of static mounts and routing.
+  `BunServerRunner` was dropping `contentSigningJWT` on the floor, which silently disabled
+  signed asset reads for every Bun project even once the prefixes were served — the config
+  arrived, the service that verifies its signatures did not.
+
+  Signed reads are refused unless every claim matches, the path included: without that, a
+  signature minted for one asset would read any other.
+
+- 33e96ab: Make a CLI served over a channel typecheck in a real project.
+
+  Both of these are unreachable for a hand-written `wireChannel`, whose routes are usually
+  bare identifiers, and unavoidable for a CLI one, whose routes are command ids.
+
+  `ChannelsMap` emitted route and message keys unquoted. A command id is a kebab or dotted
+  name far more often than not — `app-smoke`, `registry.search`, `package.upgrade-pikku` —
+  and each one ends the property early, so the generated map is not parseable TypeScript at
+  all. One project's map came out with 107 syntax errors from a single CLI channel. Keys are
+  now quoted when they are not bare identifiers, and left alone when they are, so existing
+  generated output is unchanged.
+
+  `executeRawCLIViaChannel` typed its renderers `Record<string, CorePikkuCLIRender<any>>`,
+  whose services parameter defaults to `CoreServices`. The renderers a generated client
+  passes are the app's own, typed against its `SingletonServices`, and a function taking
+  those is not assignable to one taking `CoreServices` — so the generated client failed to
+  compile for any app that adds a service, which is every app.
+
+  Rather than widen the type, it now says what is actually true on that side of the socket:
+  a renderer running on the client gets a logger and nothing else, because there is no
+  service container there to resolve anything from. `CorePikkuCLIClientRender` and
+  `ClientCLIRenderServices` are new exports of `@pikku/core/cli/channel`. They are not
+  expressible as `CorePikkuCLIRender`, whose `Services` parameter is constrained to
+  `CoreSingletonServices` and so demands a `config`, `variables` and `secrets` the client
+  cannot invent. The one cast from the app's renderer type to that shape is localised to the
+  generated client, where it is sound: generation refuses to emit the file at all if a
+  renderer reaches for a service other than `logger`.
+
+- 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.
+
+- 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.
+
 ## 0.12.74
 
 ### Patch Changes

package/dist/column-form.d.ts

@@ -0,0 +1,32 @@
+import type { HashedValue, SealedValue, WrappedValue } from './data-classification.js';
+/**
+ * SHA-256 of a credential, lowercase hex — the sole producer of `HashedValue`.
+ *
+ * Deliberately unpeppered. These are high-entropy random bearer tokens, not
+ * passwords: there is no candidate set to search, so a pepper would add a key
+ * to manage and a rotation story to own while buying nothing. A column holding
+ * a *low*-entropy secret is not a `hashed` column — it wants a password KDF and
+ * a different type entirely.
+ *
+ * Async because it runs on WebCrypto rather than `node:crypto`, so the same
+ * code path works in a Worker. Callers that hash a bearer token on every
+ * request are already async.
+ */
+export declare const hashToken: (raw: string) => Promise<HashedValue>;
+/**
+ * Assert that a string already in storage is ciphertext of the given form.
+ *
+ * The brands exist so that new writes must come from a real encrypt/hash call,
+ * but three paths legitimately hold such a value as a bare `string`: a
+ * migration backfilling rows written before the column declared its form, a
+ * test fixture, and a value arriving over the wire from a service that sealed
+ * it elsewhere. Each of those is a promise the caller is making, not something
+ * the type system can check — which is why these are named to be greppable and
+ * why there is no non-`unsafe` spelling. If one of these appears in ordinary
+ * request-handling code, that is the bug.
+ */
+export declare const unsafeAsWrapped: (stored: string) => WrappedValue;
+/** See `unsafeAsWrapped`. */
+export declare const unsafeAsSealed: (stored: string) => SealedValue;
+/** See `unsafeAsWrapped`. */
+export declare const unsafeAsHashed: (stored: string) => HashedValue;

package/dist/column-form.js

@@ -0,0 +1,42 @@
+/**
+ * SHA-256 of a credential, lowercase hex — the sole producer of `HashedValue`.
+ *
+ * Deliberately unpeppered. These are high-entropy random bearer tokens, not
+ * passwords: there is no candidate set to search, so a pepper would add a key
+ * to manage and a rotation story to own while buying nothing. A column holding
+ * a *low*-entropy secret is not a `hashed` column — it wants a password KDF and
+ * a different type entirely.
+ *
+ * Async because it runs on WebCrypto rather than `node:crypto`, so the same
+ * code path works in a Worker. Callers that hash a bearer token on every
+ * request are already async.
+ */
+export const hashToken = async (raw) => {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error('WebCrypto not available');
+    }
+    const digest = await subtle.digest('SHA-256', new TextEncoder().encode(raw));
+    let hex = '';
+    for (const byte of new Uint8Array(digest)) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return hex;
+};
+/**
+ * Assert that a string already in storage is ciphertext of the given form.
+ *
+ * The brands exist so that new writes must come from a real encrypt/hash call,
+ * but three paths legitimately hold such a value as a bare `string`: a
+ * migration backfilling rows written before the column declared its form, a
+ * test fixture, and a value arriving over the wire from a service that sealed
+ * it elsewhere. Each of those is a promise the caller is making, not something
+ * the type system can check — which is why these are named to be greppable and
+ * why there is no non-`unsafe` spelling. If one of these appears in ordinary
+ * request-handling code, that is the bug.
+ */
+export const unsafeAsWrapped = (stored) => stored;
+/** See `unsafeAsWrapped`. */
+export const unsafeAsSealed = (stored) => stored;
+/** See `unsafeAsWrapped`. */
+export const unsafeAsHashed = (stored) => stored;

package/dist/crypto-utils.d.ts

@@ -1,3 +1,4 @@
+import type { WrappedValue } from './data-classification.js';
 export declare const encryptJSON: (secret: string, value: unknown) => Promise<string>;
 export declare const decryptJSON: <T>(secret: string, token: string) => Promise<T>;
 /**
@@ -26,12 +27,22 @@ export declare const generateDEK: () => Promise<string>;
  */
 export declare const generateKEKSalt: () => string;
 export declare const deriveKEK: (passphrase: string, salt: string) => Promise<CryptoKey>;
-export declare const wrapDEK: (kek: CryptoKey, plaintextDEK: string) => Promise<string>;
+export declare const wrapDEK: (kek: CryptoKey, plaintextDEK: string) => Promise<WrappedValue>;
 export declare const unwrapDEK: (kek: CryptoKey, wrappedDEK: string) => Promise<string>;
 export interface EnvelopeEncryptResult {
-    ciphertext: string;
-    wrappedDEK: string;
+    ciphertext: WrappedValue;
+    wrappedDEK: WrappedValue;
 }
 export declare const envelopeEncrypt: (kek: CryptoKey, value: unknown) => Promise<EnvelopeEncryptResult>;
+/**
+ * Note the inputs are plain `string`, not `WrappedValue`.
+ *
+ * The brand exists to stop plaintext being *written* to a wrapped column, and
+ * a `WrappedValue` is assignable to `string`, so a branded caller still passes
+ * without a cast. Demanding the brand here would buy nothing — feeding the
+ * wrong string in already fails at the AEAD tag — while forcing a cast into
+ * every path that reads ciphertext back out of a row, a parsed envelope, or the
+ * wire, which is exactly where casts are least reviewable.
+ */
 export declare const envelopeDecrypt: <T>(kek: CryptoKey, ciphertext: string, wrappedDEK: string) => Promise<T>;
-export declare const envelopeRewrap: (oldKEK: CryptoKey, newKEK: CryptoKey, wrappedDEK: string) => Promise<string>;
+export declare const envelopeRewrap: (oldKEK: CryptoKey, newKEK: CryptoKey, wrappedDEK: string) => Promise<WrappedValue>;

package/dist/crypto-utils.js

@@ -217,8 +217,14 @@ export const generateKEKSalt = () => {
 export const deriveKEK = async (passphrase, salt) => {
     return deriveKey(passphrase, fromBase64Url(salt));
 };
+/**
+ * The one place a `WrappedValue` is minted. Every branded return below routes
+ * through here, so the assertion "these bytes really are ciphertext" is made
+ * once and audited once instead of at each call site.
+ */
+const asWrapped = (ciphertext) => ciphertext;
 export const wrapDEK = async (kek, plaintextDEK) => {
-    return encryptWithCryptoKey(kek, plaintextDEK);
+    return asWrapped(await encryptWithCryptoKey(kek, plaintextDEK));
 };
 export const unwrapDEK = async (kek, wrappedDEK) => {
     return decryptWithCryptoKey(kek, wrappedDEK);
@@ -231,10 +237,20 @@ const decryptWithDEK = async (dekBase64, token) => {
 };
 export const envelopeEncrypt = async (kek, value) => {
     const dek = await generateDEK();
-    const ciphertext = await encryptWithDEK(dek, value);
+    const ciphertext = asWrapped(await encryptWithDEK(dek, value));
     const wrappedDEK = await wrapDEK(kek, dek);
     return { ciphertext, wrappedDEK };
 };
+/**
+ * Note the inputs are plain `string`, not `WrappedValue`.
+ *
+ * The brand exists to stop plaintext being *written* to a wrapped column, and
+ * a `WrappedValue` is assignable to `string`, so a branded caller still passes
+ * without a cast. Demanding the brand here would buy nothing — feeding the
+ * wrong string in already fails at the AEAD tag — while forcing a cast into
+ * every path that reads ciphertext back out of a row, a parsed envelope, or the
+ * wire, which is exactly where casts are least reviewable.
+ */
 export const envelopeDecrypt = async (kek, ciphertext, wrappedDEK) => {
     const dek = await unwrapDEK(kek, wrappedDEK);
     return decryptWithDEK(dek, ciphertext);

package/dist/data-classification.d.ts

@@ -9,12 +9,56 @@ export type Secret<T> = T & {
 };
 export type Classification = 'public' | 'private' | 'pii' | 'secret';
 export type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null;
+/**
+ * How a column's bytes are represented at rest, as distinct from how sensitive
+ * the value is (`Classification`). The two are independent: a token hash is
+ * `secret` + `hashed` and must never be encrypted, because the hash *is* the
+ * lookup key; a live bearer token is `secret` + `plain` today and should not be.
+ *
+ * `wrapped` and `sealed` are siblings rather than one being "encrypted": both
+ * are ciphertext, and what separates them is who can read it back. Wrapped is
+ * symmetric and the application holds the key. Sealed is asymmetric and the
+ * application holds only the public half, so it can write the value and never
+ * read it. Storing one where the other is expected is silent, permanent data
+ * loss, which is why they are not collapsed into a single `encrypted`.
+ */
+export type ColumnForm = 'plain' | 'hashed' | 'wrapped' | 'sealed';
+declare const wrappedBrand: unique symbol;
+declare const sealedBrand: unique symbol;
+declare const hashedBrand: unique symbol;
+/**
+ * Ciphertext under a symmetric key the application holds — the output of
+ * `envelopeEncrypt`, `wrapDEK` or `envelopeRewrap`.
+ *
+ * Unlike `Secret<T>` the brand is REQUIRED, so a plain `string` is not
+ * assignable and a column declared `form: 'wrapped'` cannot be written with
+ * anything but genuine ciphertext. It stays assignable *to* `string`, so it
+ * still works as a query operand and serializes normally — the constraint is on
+ * construction, not on use.
+ */
+export type WrappedValue = string & {
+    readonly [wrappedBrand]: true;
+};
+/** Ciphertext under a public key whose private half the application does not
+ *  hold. Deliberately not assignable to `WrappedValue`: writing one where the
+ *  other belongs produces a row nobody can ever open. */
+export type SealedValue = string & {
+    readonly [sealedBrand]: true;
+};
+/** A one-way digest of a secret input. The brand's job is narrow — stop a *raw*
+ *  credential being written into the column that should hold its hash. */
+export type HashedValue = string & {
+    readonly [hashedBrand]: true;
+};
 export interface ColumnClassification {
     classification: Classification;
     anonymize_strategy: AnonymizeStrategy;
+    /** At-rest representation. Absent means `plain`. */
+    form?: ColumnForm;
     description?: string;
 }
 export type ClassificationManifest = {
     version: 1;
     tables: Record<string, Record<string, ColumnClassification>>;
 };
+export {};