@northstartech/cipher 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,542 @@
-# Temporary Holding Version
+# @northstartech/cipher
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK for **Northstar Cipher**, field-level encryption as a service. Keys
+never leave attested enclaves. Your database stores only `nsc:v1:…` ciphertext,
+plus optional blind-index tokens for exact-match search.
+
+* Node.js ≥ 20 (ESM). The core client also runs in browsers.
+* ORM integrations for **Prisma, Sequelize, Mongoose, Drizzle and TypeORM** ship
+  as subpath exports. The ORMs are optional peer dependencies.
+* **Northstar Search**: typo-tolerant full-text search over encrypted data, run
+  inside the enclave (see [Northstar Search](#northstar-search)).
+
+```sh
+npm install @northstartech/cipher
+```
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `NORTHSTAR_CIPHER_ENDPOINT` | `https://api.northstar.mx` | Gateway URL (`http://localhost:7080` locally) |
+| `NORTHSTAR_CIPHER_CREDENTIAL` | (required) | Workload credential `nsc_dev_…` / `nsc_live_…` |
+| `NORTHSTAR_CIPHER_KEY` | `default` | Key alias |
+| `NORTHSTAR_CIPHER_ATTESTATION` | `auto` | `auto`, `development`, `production` |
+| `NORTHSTAR_CIPHER_TRUST_ANCHOR` | none | Pinned verifier key(s) `<kid>:<b64u>`. Required in production. |
+
+## Quickstart
+
+```ts
+import { CipherError, NorthstarCipher } from '@northstartech/cipher'
+
+// One client per process. Constructing it performs no network I/O.
+const cipher = NorthstarCipher.fromEnv()
+
+// The context names the protected value. Decryption fails if any part differs.
+const context = { collection: 'citizens', field: 'passport', recordId: '123' }
+const { ciphertext } = await cipher.encrypt({ plaintext: 'G12345678', context })
+const { plaintext } = await cipher.decrypt({ ciphertext, context, purpose: 'kyc_review' })
+
+// Batches: one request per 1 000 items. Concurrent encrypt()/decrypt() calls are coalesced automatically.
+const encrypted = await cipher.encryptMany(rows.map((r) => ({ plaintext: r.passport, context: { ...context, recordId: r.id } })))
+const settled = await cipher.decryptManySettled(items) // [{ ok: true, value } | { ok: false, error }]
+
+// Exact-match search: store the blind index next to the ciphertext, then match tokens.
+const { index } = await cipher.encrypt({ plaintext: 'ana@example.com', context: { collection: 'users', field: 'email', recordId: '7' }, index: { normalization: 'email' } })
+const [tokens] = await cipher.searchTokens({ collection: 'users', field: 'email', values: ['ANA@example.com'], normalization: 'email' })
+// SELECT … WHERE email_bidx IN (…tokens)
+```
+
+Every failure throws `CipherError` (`code`, `message`, `requestId`, `status`,
+`retryable`). Nothing ever falls back to plaintext. Messages never contain
+plaintext, ciphertext or secrets. To watch the sealed traffic (counts,
+latency), pass `debug: { onWire(e) { … } }`.
+
+Before the first request, the client verifies the enclave's attestation and
+opens a session to the attested key with HPKE (RFC 9180) using the **X-Wing**
+KEM (ML-KEM-768 + X25519, a post-quantum hybrid). Recorded traffic stays
+confidential unless both ML-KEM and X25519 are broken, which protects against
+harvest-now-decrypt-later attacks. There is no fallback to a classical key
+exchange: an enclave offering anything but an X-Wing key fails with
+`ATTESTATION_FAILED`.
+
+## Encrypting files and large values
+
+`encrypt()` takes values up to 1 MiB and sends them to the enclave. For files,
+images, exports and backups, use `encryptObject()`. The SDK seals the bytes in
+your process with a random 32-byte object key (format NSOB v1, AES-256-GCM in
+64 KiB blocks), and Cipher encrypts only that key. The object never reaches
+Cipher, so the 1 MiB limit does not apply.
+
+```ts
+// The context names where the wrapped key is stored: table, column, record.
+const context = { collection: 'documents', field: 'file_key', recordId: doc.id }
+const { wrappedKey, object } = await cipher.encryptObject({ plaintext: pdfBytes, context })
+await db.documents.update(doc.id, { file_key: wrappedKey })      // nsc:v1:… with the record
+await storage.put(`documents/${doc.id}`, object)                // the encrypted bytes
+
+const pdf = await cipher.decryptObject({ object, wrappedKey, context, purpose: 'support_case' }) // Uint8Array
+```
+
+* Each call makes one request (`/v1/encrypt` or `/v1/decrypt` for the key), so
+  policy, purposes and audit apply as for fields. `keyId` and `blockLog2`
+  (12 … 24, default 16) are optional.
+* Rotation: `rewrapMany()` on the stored wrapped keys. Objects are not touched.
+* Deletion: delete the object and its wrapped key. Destroying a key version
+  makes every object whose key it wraps unreadable (crypto-shredding).
+* Any failure to open an object (another record's context, another object's
+  wrapped key, truncation, reordered blocks, a flipped bit) throws
+  `INVALID_CIPHERTEXT` with one message. Plaintext is returned only after every
+  block verifies.
+* `sealObject()` and `openObject()` are the format functions without a request,
+  for streaming and the vectors (`docs/vectors/object-v1.json`). The object key
+  is zeroed after use and never logged or cached.
+
+---
+
+## ORM integrations
+
+| ORM | Import | Entry point |
+|---|---|---|
+| Prisma 7 | `@northstartech/cipher/prisma` | `withNorthstarCipher(cipher, { models })` client extension |
+| Sequelize 6 | `@northstartech/cipher/sequelize` | `northstarCipher(Model, cipher, { fields })` |
+| Mongoose 9 | `@northstartech/cipher/mongoose` | `schema.plugin(northstarCipherPlugin, { cipher, fields })` |
+| Drizzle | `@northstartech/cipher/drizzle` | `encrypted(table, fields)`, `northstarDrizzle(cipher)`, `cipherEq()` |
+| TypeORM 1 | `@northstartech/cipher/typeorm` | `@Encrypted()` + `northstarCipherSubscriber(cipher)` |
+
+### Common behaviour
+
+All five integrations follow the same conventions, so data written by one SDK
+(any language) can be read by another.
+
+* **Context.** `collection` is the table (or Mongo collection) name, `field` is
+  the column name, and `record_id` is the primary key as a string. UUIDs are
+  lowercased and ObjectIds use their hex form. Changing a primary key would
+  invalidate its ciphertext, so the integrations refuse to do it.
+* **Columns.** Encrypted columns are `text`. Ciphertext is about 180
+  characters plus 4/3 × the plaintext length. A searchable field `email` stores
+  its blind index in `email_bidx` (`varchar(64)`, indexed), written in the same
+  statement. Encrypted values are strings; serialize other types first.
+* **Add a CHECK constraint** to every encrypted column so raw SQL can never
+  store plaintext:
+
+  ```sql
+  ALTER TABLE todos ADD CONSTRAINT todos_title_nsc CHECK (title IS NULL OR title LIKE 'nsc:%');
+  ```
+
+* **Writes.** Values are encrypted before the row is written: all encrypted
+  fields of a record go in one batch request, and bulk operations send one
+  batch for all their records. The record id must be known before the write:
+
+  | Primary key | Strategy |
+  |---|---|
+  | Explicit or client-generated (UUID, cuid, ULID, ObjectId, `$defaultFn`) | used directly |
+  | PostgreSQL serial/identity | reserved first with `nextval(pg_get_serial_sequence(…))` (Prisma, Sequelize, Drizzle) |
+  | Auto-increment elsewhere (SQLite, MySQL), and TypeORM generated integer keys | two-phase write: insert the `nsc:pending:v1` sentinel, then replace it with ciphertext bound to the generated id, in the same transaction when one is available |
+
+  If encryption fails, the write is aborted. A failed second phase deletes the
+  pending row. The sentinel can never be decrypted, so a crash leaves no
+  plaintext behind.
+* **Reads.** Every encrypted value of every row a query returns (including
+  eagerly loaded relations) is decrypted in one batch, chunked at 1 000 values.
+  Listing 100 rows with two encrypted fields costs one request, not 200.
+* **Fail closed.** A stored value that is not `nsc:v1:` ciphertext (plaintext,
+  the pending sentinel, a foreign value) throws `INVALID_CIPHERTEXT`. So does
+  ciphertext that was tampered with or moved to another record. Reading legacy
+  plaintext requires an explicit `readLegacyPlaintext: true`, intended for
+  migrations only.
+* **Search.** Only exact match is supported, through the blind index, using the
+  field's normalization (`exact`, `case_insensitive`, `email`, `alphanumeric`,
+  `digits`). **`LIKE`, ranges, ordering and aggregates do not work on encrypted
+  fields.** Where an integration can see such a query, it throws instead of
+  silently returning wrong results. Blind indexes reveal equality (rows with the
+  same value share a token), so do not index low-cardinality fields such as
+  status, booleans or country.
+* **Options** shared by every integration:
+  * `keyId` sets the key alias.
+  * `purpose` is the audited decrypt purpose.
+  * `readLegacyPlaintext` is for migrations only.
+
+| Error code | When |
+|---|---|
+| `CONFIGURATION_ERROR` | Misconfiguration: unknown field, non-text column, no blind-index column, unsupported key |
+| `INVALID_REQUEST` | An operation that cannot be encrypted correctly: bulk update of encrypted fields, filter on ciphertext, primary-key change |
+| `INVALID_CIPHERTEXT` | Stored value tampered, moved, plaintext or pending |
+| service codes | `KEY_NOT_FOUND`, `PERMISSION_DENIED`, `RATE_LIMITED`, … as returned by the service |
+
+> **What bypasses the integrations.** Raw SQL and driver calls do, as do
+> `$executeRaw`, `Model.collection.*`, Sequelize `hooks: false` and TypeORM
+> `listeners: false`. The CHECK constraint is the backstop for all of them.
+> Sequelize refuses `hooks: false` writes that would store plaintext.
+
+### Prisma
+
+Requires Prisma 7 (the `prisma-client` generator with a driver adapter).
+
+```prisma
+model Todo {
+  id         Int     @id @default(autoincrement())
+  title      String?                  // encrypted
+  email      String?                  // encrypted + searchable
+  email_bidx String? @db.VarChar(64)
+  @@index([email_bidx])
+  @@map("todos")
+}
+```
+
+```ts
+import { PrismaPg } from '@prisma/adapter-pg'
+import { withNorthstarCipher } from '@northstartech/cipher/prisma'
+import { PrismaClient } from './generated/prisma/client.js'
+
+const nsc = withNorthstarCipher(cipher, {
+  models: {
+    Todo: { title: true, email: { searchable: 'email' } },
+    Note: { $id: 'cuid', body: true }, // match the id format of @default(cuid())
+  },
+})
+const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString }) }).$extends(nsc)
+
+await prisma.todo.create({ data: { title: 'Buy milk', email: 'Ana@example.com' } })
+await prisma.todo.update({ where: { id }, data: { email: 'new@example.com' } })
+const todos = await prisma.todo.findMany({ include: { owner: true } }) // one decrypt request
+
+const mine = await prisma.todo.findMany({ where: await prisma.todo.cipherWhere('email', 'ana@example.com') })
+// or: where: await nsc.cipherWhere('Todo', 'email', ['a@x.com', 'b@x.com'])  →  { email_bidx: { in: [...] } }
+```
+
+**Ids.** Configure them with `$id: '<strategy>'` or `$id: { field, strategy }`.
+* `String` ids are generated client-side. The default is `'uuid'`; also
+  available are `'uuidv7'`, `'cuid'`, `'cuid2'`, `'ulid'`, `'nanoid'`, or a
+  function.
+* `Int`/`BigInt` ids on PostgreSQL/CockroachDB are reserved from the sequence
+  (`'sequence'`).
+* Integer auto-increment ids on other databases are a configuration error.
+  Use a client-generated id, or `$id: 'explicit'` and always pass ids.
+* Composite primary keys are not supported.
+
+The extension handles `create`, `createMany`, `createManyAndReturn`, `update`,
+`upsert`, `delete` and every `find*`, including `select`, `omit`, `include`,
+nested relations and the fluent API. When a selection includes encrypted
+fields but omits the id, the extension fetches the id and strips it from the
+result.
+
+**Limitations.**
+* `updateMany`/`updateManyAndReturn` cannot set encrypted fields, because each
+  row needs its own ciphertext. Update records individually.
+* Nested writes into an encrypted model (`owner: { create: { ssn } }`) are
+  refused. Write that model through its own delegate.
+* With a reserved integer id, Prisma's relation inputs (`owner: { connect }`)
+  cannot carry the id. Set the foreign-key scalar (`ownerId`) instead.
+* `update`/`upsert` addressed by a non-id unique field look the id up first
+  through the base client, outside any interactive transaction. Inside
+  `$transaction(async (tx) => …)`, address rows by id.
+* Reserved sequence values are not rolled back, so gaps are normal.
+* `where`, `orderBy`, `distinct`, `groupBy`, `_min` and `_max` on encrypted
+  fields are refused. Null checks are allowed.
+* `$queryRaw` returns ciphertext. Decrypt it with the core client.
+
+### Sequelize
+
+```ts
+import { northstarCipher } from '@northstartech/cipher/sequelize'
+
+class Todo extends Model {}
+Todo.init({
+  id: { type: DataTypes.INTEGER, autoIncrement: true, primaryKey: true },
+  title: { type: DataTypes.TEXT, validate: { len: [1, 60] } }, // validators see plaintext
+  email: { type: DataTypes.TEXT, validate: { isEmail: true } },
+  email_bidx: DataTypes.STRING(64),
+}, { sequelize, tableName: 'todos' })
+
+const T = northstarCipher(Todo, cipher, { fields: ['title', { name: 'email', searchable: 'email' }] })
+
+await Todo.create({ title: 'Buy milk', email: 'ana@example.com' })
+await Todo.bulkCreate(rows, { validate: true })                  // one encrypt request
+const all = await Todo.findAll({ include: [Owner] })             // one decrypt request, includes too
+const mine = await Todo.findAll({ where: await T.cipherWhere('email', 'ANA@example.com') })
+```
+
+**Ids.** Explicit ids and defaults such as `UUIDV4` are used directly.
+`autoIncrement` keys are reserved from the sequence on PostgreSQL. Other
+dialects use the two-phase write: `afterCreate`/`afterBulkCreate` replace the
+sentinel inside `options.transaction` when given, and delete the row if that
+fails.
+
+**Writes and reads.**
+* Instances hold plaintext after `create`/`save`, and `changed()` is clean.
+* Validators always run on plaintext, including bulk validation and
+  Sequelize's re-validation of hook-changed attributes.
+* A static `Model.update()` that sets encrypted attributes switches to
+  per-instance hooks, so every row gets its own ciphertext.
+* `afterFind` decrypts all returned instances, their eager-loaded includes and
+  `raw: true` rows in one batch. Select the primary key together with encrypted
+  attributes.
+
+**Refused.**
+* `Model.upsert()` with encrypted attributes. Sequelize builds the statement
+  before hooks run, so use `findOrCreate`/`save` instead.
+* `updateOnDuplicate` on encrypted attributes.
+* `ignoreDuplicates` combined with the two-phase write.
+* `where` or `order` on encrypted attributes.
+* Primary-key changes.
+* `hooks: false` writes that would store plaintext.
+
+### Mongoose
+
+```ts
+import { northstarCipherPlugin, type CipherModelStatics, type CipherQueryHelpers } from '@northstartech/cipher/mongoose'
+
+const schema = new Schema({
+  title: { type: String, maxlength: 60 },
+  email: { type: String, lowercase: true, trim: true }, // setters and validators apply to plaintext
+  profile: { ssn: String },
+})
+schema.plugin(northstarCipherPlugin, { cipher, fields: ['title', { path: 'email', searchable: 'email' }, { path: 'profile.ssn', searchable: 'alphanumeric' }] })
+const Todo = model('Todo', schema)
+
+await Todo.create({ title: 'Buy milk', email: 'Ana@example.com' })
+await Todo.insertMany(docs)                                         // one encrypt request
+const todos = await Todo.find().populate('owner')                   // one decrypt request per model
+const mine = await Todo.find().cipherWhere('email', 'ana@example.com')
+const one = await Todo.findOne(await Todo.cipherFilter('profile.ssn', 'G-1234'))
+```
+
+**Paths and ids.** `_id` is the record id: ObjectIds exist before the insert,
+so no extra round trip is needed. Encrypted paths are top-level or
+nested-object `String` paths; arrays and subdocuments are not supported. The
+plugin adds `<path>_bidx` (indexed) for searchable paths.
+
+**Writes.**
+* `save()`, `create()` and `insertMany()` encrypt. `insertMany()` uses one
+  batch for all documents.
+* `updateOne`, `findOneAndUpdate`, `replaceOne` and `findOneAndReplace` encrypt
+  `$set`, `$setOnInsert`, implicit sets and replacements. The update is bound
+  to the single matched document: its `_id` is resolved with the same filter
+  and sort, and the filter is pinned to it. Upserts insert under a fresh
+  `_id`. `$unset` also clears the blind index.
+
+**Refused.**
+* `updateMany` and `bulkWrite` that write encrypted paths.
+* Other update operators on encrypted paths.
+* Filters, `sort` and `distinct` on encrypted paths. Null and `$exists`
+  checks are allowed.
+* Aggregation-pipeline updates that touch encrypted paths.
+
+**Reads.** `find`, `findOne` and the `findOneAnd*` methods decrypt both
+documents and `lean()` results. `aggregate()`, cursors and change streams
+return ciphertext; pass the results to `Model.cipherDecrypt(docs)`.
+
+**TypeScript.** Use `Model<T, CipherQueryHelpers> & CipherModelStatics`.
+
+### Drizzle
+
+Drizzle has no async hooks, so encryption is an explicit, typed step around
+your queries.
+
+```ts
+import { cipherEq, encrypted, northstarDrizzle, pendingRow, PENDING_SENTINEL } from '@northstartech/cipher/drizzle'
+
+export const todos = encrypted(
+  pgTable('todos', { id: serial('id').primaryKey(), title: text('title'), email: text('email'), emailBidx: varchar('email_bidx', { length: 64 }) }),
+  { title: true, email: { searchable: 'email' } }, // `email_bidx` is found by column name (or set indexField)
+)
+const nsc = northstarDrizzle(cipher, { db }) // db reserves PostgreSQL serial ids
+
+await db.insert(todos).values(await nsc.encryptRows(todos, [{ title: 'Buy milk', email: 'ana@example.com' }]))
+const rows = await nsc.decryptRows(todos, await db.select().from(todos))      // one decrypt request
+const tokens = await nsc.searchTokens(todos.email, 'ANA@example.com')
+const mine = await nsc.decryptRows(todos, await db.select().from(todos).where(cipherEq(todos.email, tokens)))
+await db.update(todos).set(await nsc.encryptRow(todos, { email: 'new@example.com' }, { recordId: id })).where(eq(todos.id, id))
+```
+
+**Ids.**
+* An id already in the row is used.
+* Otherwise the primary key's `$defaultFn` (for example
+  `uuid('id').$defaultFn(() => crypto.randomUUID())`) is called.
+* Otherwise a PostgreSQL `serial`/identity key is reserved with one `nextval`
+  query. Pass `{ db: tx }` inside transactions. `generatedAlwaysAsIdentity`
+  rejects explicit ids; use `generatedByDefaultAsIdentity`.
+* For databases where the id only exists after the insert, use the two-phase
+  write:
+
+```ts
+const [{ id }] = await db.insert(tickets).values(pendingRow(tickets, input)).returning({ id: tickets.id })
+await db.update(tickets).set(await nsc.encryptRow(tickets, input, { recordId: id }))
+  .where(and(eq(tickets.id, id), eq(tickets.subject, PENDING_SENTINEL)))
+```
+
+**Reads.** `decryptRows` expects rows keyed like the table, including partial
+selects that keep the primary key. For joins, pass each table's sub-object.
+Because writes are explicit, CHECK constraints matter most here.
+
+### TypeORM
+
+```ts
+import { Encrypted, cipherWhere, northstarCipherSubscriber } from '@northstartech/cipher/typeorm'
+
+@Entity('todos')
+export class Todo {
+  @PrimaryGeneratedColumn('uuid') id!: string
+  @Encrypted() @Column({ type: 'text', nullable: true }) title!: string | null
+  @Encrypted({ searchable: 'email' }) @Column({ type: 'text', nullable: true }) email!: string | null
+  @Index() @Column({ type: 'varchar', length: 64, nullable: true }) email_bidx!: string | null
+}
+
+const ds = new DataSource({ /* … */ entities: [Todo], subscribers: [northstarCipherSubscriber(cipher)] })
+await ds.getRepository(Todo).save(todos)                         // encryption coalesced into one request
+const all = await ds.getRepository(Todo).find({ relations: { owner: true } })
+const mine = await ds.getRepository(Todo).findBy(await cipherWhere(ds, Todo, 'email', 'ANA@example.com'))
+```
+
+`@Encrypted()` uses TypeORM's legacy decorators (`experimentalDecorators`).
+Declare an explicit `text` column type. You can also register an instance with
+`dataSource.subscribers.push(new NorthstarCipherSubscriber(cipher))`.
+
+**Ids.**
+* `uuid` primary keys are generated client-side in `beforeInsert`.
+* Generated integer keys (`increment`, `identity`, `rowid`) use the two-phase
+  write in `afterInsert`, inside `save()`'s transaction. TypeORM never sends
+  explicit values for them on PostgreSQL. On failure, the row is removed and
+  the transaction rolls back.
+* `@PrimaryColumn()` values must be set before saving.
+
+**Writes and reads.**
+* `save()` re-encrypts only properties that differ from the loaded entity.
+* `afterLoad` decrypts each value through the SDK's auto-batching, so a query
+  costs one request per 1 000 values. Keep the client's `batching` enabled.
+
+**Refused and not intercepted.**
+* `repository.update()` or `QueryBuilder.update()` setting encrypted columns
+  is refused. Load the entity and `save()` it.
+* TypeORM has no pre-find hook, so `where` and `order` on encrypted columns
+  are not intercepted. Use `cipherWhere()`.
+* `upsert()` must conflict on the primary key.
+
+---
+
+## Northstar Search
+
+Encrypted full-text search that runs inside the attested enclave. Documents and
+queries travel sealed to the enclave session; index files are encrypted at rest
+under a key only the enclave can unwrap. Indexing needs `cipher.index`, queries
+need `cipher.search`, and returning values (`select`, `highlight`) or indexing
+ciphertext needs `cipher.decrypt`.
+
+```ts
+const customers = cipher.index('customers')   // no request until a method is called
+
+// Create the index, or confirm it exists with this schema (outcome: created | unchanged).
+await customers.ensure({
+  language: 'spanish',                                       // english, spanish, portuguese, french, german, italian, dutch, none
+  fields: { name: 'text', email: 'keyword', city: 'keyword', balance: 'number', joined: 'date', vip: 'bool' },
+})                                                           // or fields: [{ name, type, boost?, language? }]
+
+// Add or replace documents ({ [id]: fields } or [{ id, fields }]); chunked by 1 000.
+await customers.upsert({
+  42: { name: 'Ana García', city: 'CDMX', balance: 1500, joined: new Date() },
+  // Ciphertext is decrypted inside the enclave. A bare `nsc:v1:` string uses the
+  // context { collection: <index or `collection` option>, field: <field>, record_id: <id> } …
+  43: { name: storedNameCiphertext, city: 'GDL' },
+  // … or give the context explicitly:
+  44: { name: SearchIndex.ciphertext(row.name, { collection: 'customers', field: 'name', recordId: 44 }) },
+}, { wait: true })                                           // wait: return once searchable
+await customers.upsert({ 42: { city: 'MTY' } }, { mode: 'merge' }) // only these fields change (null removes one)
+await customers.delete([43])
+
+const r = await customers.search({
+  q: 'ana garsia',                                           // typo tolerant; fuzzy: auto | off | one | two
+  filter: { city: ['CDMX', 'MTY'], balance: { gte: 1000 }, vip: { exists: false } }, // value | [values] | {gt,gte,lt,lte} | {exists} | {not}
+  sort: [{ field: 'balance', desc: true }],
+  limit: 20, offset: 0, facets: ['city'],
+  select: ['name', 'city'], highlight: ['name'], purpose: 'support', // values are returned decrypted
+})
+// r.hits = [{ id: '42', score: 3.1, fields: { name: 'Ana García', city: 'MTY' }, highlights: { name: '<mark>Ana</mark> <mark>García</mark>' } }]
+// r.total, r.facets.city = [{ value: 'MTY', count: 1 }], r.tookMs
+
+await customers.describe()                                   // { index, keyId, active: { version, documents, diskBytes, … }, building? }
+await cipher.searchIndexes()                                 // every index this credential may use
+await customers.drop()                                       // true, or false when there was none
+```
+
+**Changing the schema without downtime.** `ensure(newSchema)` fails with
+`CONFLICT` when the schema changed. `ensure(newSchema, { rebuild: true })` builds
+a new version next to the live one: writes reach both, queries keep using the
+live one. Reindex every record, then `flush({ optimize: true })` and
+`activate()` to switch over (the old version is deleted).
+
+A missing index raises `NOT_FOUND`. Documents the enclave could not index (e.g.
+a field missing from the schema, a ciphertext bound to another context) are
+listed in `errors`; the rest of the request is indexed.
+
+### Search with the ORM integrations
+
+Each integration builds documents whose encrypted fields are the **stored
+ciphertext with the exact context the integration encrypted it with**
+(collection = table, field = column, record id = primary key), so indexing
+never decrypts in your process. Plain attributes are sent as values (dates as
+RFC 3339). Integrations with lifecycle hooks keep an index in sync; sync writes
+use `merge` mode, so partially loaded records do not erase indexed fields.
+
+```ts
+const index = cipher.index('todos')
+await index.ensure({ fields: { title: 'text', email: 'keyword', done: 'bool' } })
+
+// Sequelize: create/save/destroy, bulkCreate, Model.update/destroy (after commit inside a transaction)
+northstarCipher(Todo, cipher, { fields: ['title', { name: 'email', searchable: 'email' }], search: { index, fields: ['title', 'email', 'done'] } })
+await index.upsert(Todo.cipherSearchDocuments(await Todo.findAll({ hooks: false } as FindOptions))) // reindex
+
+// TypeORM: save/remove/softRemove, applied when the transaction commits (dropped on rollback)
+new DataSource({ …, subscribers: [northstarCipherSubscriber(cipher, { search: [{ entity: Todo, index, fields: ['title', 'email', 'done'] }] })] })
+await index.upsert(searchDocuments(ds, Todo, await ds.query('SELECT * FROM todos'), ['title', 'email', 'done']))
+
+// Mongoose: save, insertMany, doc.deleteOne(), findOneAndDelete()
+todoSchema.plugin(northstarCipherPlugin, { cipher, fields: ['title'], search: { index, fields: ['title', 'done'] } })
+await index.upsert(Todo.cipherSearchDocuments(await Todo.collection.find().toArray()))
+
+// Prisma and Drizzle (no lifecycle hooks): build documents from stored rows
+await index.upsert(nsc.searchDocuments('Todo', await base.todo.findMany(), ['title', 'email', 'done'])) // base = client without the extension
+await index.upsert(searchDocuments(todos, await db.select().from(todos), ['title', 'email', 'done']))   // @northstartech/cipher/drizzle
+```
+
+Sync options: `{ index, fields, wait?, onError? }`. Without `onError`, an index
+failure rejects the ORM call, or is logged when it happens after a commit.
+Writes the hooks cannot see (raw SQL, `QueryBuilder`/query updates,
+`deleteMany`, Sequelize `upsert()`) are not tracked: reindex after them. Load
+hits back with your ORM (`where: { id: hits.map((h) => h.id) }`) and keep the
+hit order.
+
+---
+
+## Running the tests
+
+`npx vitest run` runs three groups:
+
+* The protocol vector tests (`docs/vectors/protocol-v1.json`, plus the X-Wing
+  vectors `xwing-v1.json` and the draft-ietf-hpke-pq reference `xwing-reference.json`)
+  and the object vectors (`object-v1.json`, `test/object-vectors.test.ts`).
+* The object encryption tests (`test/object.test.ts`): mocked transport, and a
+  live flow with a 3 MiB object (one small `/v1/encrypt`, tampering, rewrap).
+* The Northstar Search unit tests (`test/search.test.ts`, mocked transport) and
+  its live flow (index `sdk_ts_<random>`: ensure, ciphertext indexing, typos,
+  filters, facets, highlights, merge, delete, rebuild + activate, drop).
+* The live ORM integration tests, including search sync. They need the local stack
+  (`curl localhost:7080/health/ready`) and a credential:
+
+```sh
+node ../../scripts/dev-provision.mjs --email node-orm@northstar.mx --project "Node ORMs" --out .test-credential.env
+npx vitest run
+```
+
+* PostgreSQL defaults to `postgres://postgres@127.0.0.1:5432`; override it
+  with `NSC_TEST_PG_URL`. The databases `nsc_sdk_node_{prisma,sequelize,sequelize_search,drizzle,typeorm}`
+  are dropped and recreated on each run; search indexes `sdk_ts_*` are dropped at the end.
+* MongoDB runs in `mongodb-memory-server`, and SQLite runs in memory.
+* The Prisma test client is generated into `test/prisma/generated/`.
+* Without a credential, the live suites are skipped with a notice.
+
+Each suite proves four things:
+* Only ciphertext and tokens reach the database (checked with raw queries).
+* Listing 100 rows takes at most 2 decrypt requests (counted with `debug.onWire`).
+* Exact-match search works.
+* Tampered, swapped, pending and plaintext values throw.