Merge pull request #296 from cipherstash/usability-1

fix(stack): PR_BYPASS usability issues and bun env support

Author: calvinbrewer

docs/reference/model-operations.md

@@ -113,60 +113,66 @@ const decryptedUsers = decryptedResult.data;
 
 ## Type safety
 
-### Using type parameters
+### Schema-aware return types (recommended)
 
-`@cipherstash/stack` provides strong TypeScript support through generic type parameters:
+`encryptModel` and `bulkEncryptModels` return **schema-aware types** when you let TypeScript infer the type parameters from the arguments.
+Fields matching the table schema are typed as `Encrypted`, while other fields retain their original types:
 
 ```typescript
-// Define your model type
+import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema";
+
 type User = {
   id: string;
-  email: string | null;
-  address: string | null;
+  email: string;
+  address: string;
   createdAt: Date;
-  metadata?: {
-    preferences?: {
-      notifications: boolean;
-      theme: string;
-    };
-  };
 };
 
-// Use the type parameter for type safety
-const encryptedResult = await client.encryptModel<User>(user, users);
-const decryptedResult = await client.decryptModel<User>(encryptedUser);
+const users = encryptedTable("users", {
+  email: encryptedColumn("email").freeTextSearch(),
+  address: encryptedColumn("address"),
+});
+
+// Let TypeScript infer the return type from the schema
+const encryptedResult = await client.encryptModel(user, users);
+
+// encryptedResult.data.email  -> Encrypted (schema field)
+// encryptedResult.data.address -> Encrypted (schema field)
+// encryptedResult.data.id      -> string    (not in schema)
+// encryptedResult.data.createdAt -> Date    (not in schema)
+
+// Decryption works the same way
+const decryptedResult = await client.decryptModel(encryptedResult.data);
 
 // Bulk operations
-const bulkEncryptedResult = await client.bulkEncryptModels<User>(
-  userModels,
-  users
+const bulkEncryptedResult = await client.bulkEncryptModels(userModels, users);
+const bulkDecryptedResult = await client.bulkDecryptModels(
+  bulkEncryptedResult.data
 );
-const bulkDecryptedResult =
-  await client.bulkDecryptModels<User>(encryptedUsers);
 ```
 
 The type system ensures:
 
-- Type safety for input models
+- Schema-defined fields are typed as `Encrypted` in the return value
+- Non-schema fields retain their original types
 - Correct handling of optional and nullable fields
 - Preservation of nested object structures
-- Type safety for encrypted and decrypted results
 
-### Type inference from schema
+### Using explicit type parameters
 
-The model operations can infer types from your schema definition:
+You can still pass an explicit type parameter for backward compatibility. When you do, the schema type parameter defaults to the widened `ProtectTableColumn`, and the return type degrades gracefully to your provided type (same behavior as before):
 
 ```typescript
-const users = encryptedTable("users", {
-  email: encryptedColumn("email").freeTextSearch(),
-  address: encryptedColumn("address"),
-});
+// Explicit type parameter — return type is User (no schema-aware mapping)
+const result = await client.encryptModel<User>(user, users);
 
-// Types are inferred from the schema
-const result = await client.encryptModel(user, users);
-// Result type includes encrypted fields for email and address
+// For full schema-aware types with explicit parameters, provide both:
+const result = await client.encryptModel<User, typeof users>(user, users);
 ```
 
+> [!TIP]
+> For the best developer experience, omit the type parameter and let TypeScript infer the schema-aware return type from the `table` argument.
+
 ## Identity-aware model operations
 
 All model operations support lock contexts for identity-aware encryption:

packages/stack/README.md

@@ -139,29 +139,27 @@ const decrypted = await client.decrypt(encrypted.data)
 
 Encrypt or decrypt an entire object. Only fields matching your schema are encrypted; other fields pass through unchanged.
 
+The return type is **schema-aware**: fields matching the table schema are typed as `Encrypted`, while other fields retain their original types. For best results, let TypeScript infer the type parameters from the arguments:
+
 ```typescript
+type User = { id: string; email: string; createdAt: Date }
+
 const user = {
   id: "user_123",
   email: "alice@example.com",  // defined in schema -> encrypted
   createdAt: new Date(),       // not in schema -> unchanged
 }
 
-// Encrypt a model
+// Let TypeScript infer the return type from the schema
 const encryptedResult = await client.encryptModel(user, users)
+// encryptedResult.data.email    -> Encrypted
+// encryptedResult.data.id       -> string
+// encryptedResult.data.createdAt -> Date
 
 // Decrypt a model
 const decryptedResult = await client.decryptModel(encryptedResult.data)
 ```
 
-Type-safe generics are supported:
-
-```typescript
-type User = { id: string; email: string; createdAt: Date }
-
-const result = await client.encryptModel<User>(user, users)
-const back = await client.decryptModel<User>(result.data)
-```
-
 ### Bulk Operations
 
 All bulk methods make a single call to ZeroKMS regardless of the number of records, while still using a unique key per value.
@@ -592,11 +590,11 @@ function Encryption(config: EncryptionClientConfig): Promise<EncryptionClient>
 | `decrypt` | `(encryptedData)` | `DecryptOperation` (thenable) |
 | `encryptQuery` | `(plaintext, { column, table, queryType?, returnType? })` | `EncryptQueryOperation` (thenable) |
 | `encryptQuery` | `(terms: ScalarQueryTerm[])` | `BatchEncryptQueryOperation` (thenable) |
-| `encryptModel` | `(model, table)` | `EncryptModelOperation<T>` (thenable) |
+| `encryptModel` | `(model, table)` | `EncryptModelOperation<EncryptedFromSchema<T, S>>` (thenable) |
 | `decryptModel` | `(encryptedModel)` | `DecryptModelOperation<T>` (thenable) |
 | `bulkEncrypt` | `(plaintexts, { column, table })` | `BulkEncryptOperation` (thenable) |
 | `bulkDecrypt` | `(encryptedPayloads)` | `BulkDecryptOperation` (thenable) |
-| `bulkEncryptModels` | `(models, table)` | `BulkEncryptModelsOperation<T>` (thenable) |
+| `bulkEncryptModels` | `(models, table)` | `BulkEncryptModelsOperation<EncryptedFromSchema<T, S>>` (thenable) |
 | `bulkDecryptModels` | `(encryptedModels)` | `BulkDecryptModelsOperation<T>` (thenable) |
 
 All operations are thenable (awaitable) and support `.withLockContext(lockContext)` for identity-aware encryption.

packages/stack/__tests__/types.test-d.ts

@@ -13,6 +13,7 @@ import type {
   DecryptedFields,
   Encrypted,
   EncryptedFields,
+  EncryptedFromSchema,
   EncryptedReturnType,
   KeysetIdentifier,
   OtherFields,
@@ -110,4 +111,35 @@ describe('Type inference', () => {
     type Enc = InferEncrypted<typeof table>
     expectTypeOf<Enc>().toMatchTypeOf<{ email: Encrypted }>()
   })
+
+  it('EncryptedFromSchema maps schema fields to Encrypted, leaves others unchanged', () => {
+    type User = { id: string; email: string; createdAt: Date }
+    type Schema = { email: ProtectColumn }
+    type Result = EncryptedFromSchema<User, Schema>
+    expectTypeOf<Result>().toEqualTypeOf<{
+      id: string
+      email: Encrypted
+      createdAt: Date
+    }>()
+  })
+
+  it('EncryptedFromSchema with widened ProtectTableColumn degrades to T', () => {
+    type User = { id: string; email: string }
+    type Result = EncryptedFromSchema<User, ProtectTableColumn>
+    // When S is the wide ProtectTableColumn, S[K] is the full union, not ProtectColumn alone.
+    // The conditional [S[K]] extends [ProtectColumn | ProtectValue] fails, so fields stay as-is.
+    expectTypeOf<Result>().toEqualTypeOf<{ id: string; email: string }>()
+  })
+
+  it('Decrypted reverses EncryptedFromSchema correctly', () => {
+    type User = { id: string; email: string; createdAt: Date }
+    type Schema = { email: ProtectColumn }
+    type EncryptedUser = EncryptedFromSchema<User, Schema>
+    type DecryptedUser = Decrypted<EncryptedUser>
+    expectTypeOf<DecryptedUser>().toMatchTypeOf<{
+      id: string
+      email: string
+      createdAt: Date
+    }>()
+  })
 })

packages/stack/src/encryption/ffi/index.ts

@@ -9,10 +9,10 @@ import type {
   BulkDecryptPayload,
   BulkEncryptPayload,
   Client,
-  Decrypted,
   EncryptOptions,
   EncryptQueryOptions,
   Encrypted,
+  EncryptedFromSchema,
   KeysetIdentifier,
   ScalarQueryTerm,
 } from '@/types'
@@ -83,10 +83,10 @@ export class EncryptionClient {
         this.client = await newClient({
           encryptConfig: validated,
           clientOpts: {
-            workspaceCrn: config.workspaceCrn,
-            accessKey: config.accessKey,
-            clientId: config.clientId,
-            clientKey: config.clientKey,
+            workspaceCrn: config.workspaceCrn ?? process.env.CS_WORKSPACE_CRN,
+            accessKey: config.accessKey ?? process.env.CS_CLIENT_ACCESS_KEY,
+            clientId: config.clientId ?? process.env.CS_CLIENT_ID,
+            clientKey: config.clientKey ?? process.env.CS_CLIENT_KEY,
             keyset: toFfiKeysetIdentifier(config.keyset),
           },
         })
@@ -324,10 +324,16 @@ export class EncryptionClient {
    * All other fields are passed through unchanged. Returns a thenable operation
    * that supports `.withLockContext()` for identity-aware encryption.
    *
+   * The return type is **schema-aware**: fields matching the table schema are
+   * typed as `Encrypted`, while other fields retain their original types. For
+   * best results, let TypeScript infer the type parameters from the arguments
+   * rather than providing an explicit type argument.
+   *
    * @param input - The model object with plaintext values to encrypt.
    * @param table - The table schema defining which fields to encrypt.
-   * @returns An `EncryptModelOperation<T>` that can be awaited to get a `Result`
-   *   containing the model with encrypted fields, or an `EncryptionError`.
+   * @returns An `EncryptModelOperation` that can be awaited to get a `Result`
+   *   containing the model with schema-defined fields typed as `Encrypted`,
+   *   or an `EncryptionError`.
    *
    * @example
    * ```typescript
@@ -342,24 +348,26 @@ export class EncryptionClient {
    *
    * const client = await Encryption({ schemas: [usersSchema] })
    *
-   * const result = await client.encryptModel<User>(
+   * // Let TypeScript infer the return type from the schema.
+   * // result.data.email is typed as `Encrypted`, result.data.id stays `string`.
+   * const result = await client.encryptModel(
    *   { id: "user_123", email: "alice@example.com", createdAt: new Date() },
    *   usersSchema,
    * )
    *
    * if (result.failure) {
    *   console.error(result.failure.message)
    * } else {
-   *   // result.data.id is unchanged, result.data.email is encrypted
-   *   console.log(result.data)
+   *   console.log(result.data.id)    // string
+   *   console.log(result.data.email) // Encrypted
    * }
    * ```
    */
-  encryptModel<T extends Record<string, unknown>>(
-    input: Decrypted<T>,
-    table: ProtectTable<ProtectTableColumn>,
-  ): EncryptModelOperation<T> {
-    return new EncryptModelOperation(this.client, input, table)
+  encryptModel<T extends Record<string, unknown>, S extends ProtectTableColumn = ProtectTableColumn>(
+    input: T,
+    table: ProtectTable<S>,
+  ): EncryptModelOperation<EncryptedFromSchema<T, S>> {
+    return new EncryptModelOperation(this.client, input as Record<string, unknown>, table)
   }
 
   /**
@@ -403,10 +411,15 @@ export class EncryptionClient {
    * while still using a unique key for each encrypted value. Only fields
    * matching the table schema are encrypted; other fields pass through unchanged.
    *
+   * The return type is **schema-aware**: fields matching the table schema are
+   * typed as `Encrypted`, while other fields retain their original types. For
+   * best results, let TypeScript infer the type parameters from the arguments.
+   *
    * @param input - An array of model objects with plaintext values to encrypt.
    * @param table - The table schema defining which fields to encrypt.
-   * @returns A `BulkEncryptModelsOperation<T>` that can be awaited to get a `Result`
-   *   containing an array of models with encrypted fields, or an `EncryptionError`.
+   * @returns A `BulkEncryptModelsOperation` that can be awaited to get a `Result`
+   *   containing an array of models with schema-defined fields typed as `Encrypted`,
+   *   or an `EncryptionError`.
    *
    * @example
    * ```typescript
@@ -421,7 +434,9 @@ export class EncryptionClient {
    *
    * const client = await Encryption({ schemas: [usersSchema] })
    *
-   * const result = await client.bulkEncryptModels<User>(
+   * // Let TypeScript infer the return type from the schema.
+   * // Each item's email is typed as `Encrypted`, id stays `string`.
+   * const result = await client.bulkEncryptModels(
    *   [
    *     { id: "1", email: "alice@example.com" },
    *     { id: "2", email: "bob@example.com" },
@@ -434,11 +449,11 @@ export class EncryptionClient {
    * }
    * ```
    */
-  bulkEncryptModels<T extends Record<string, unknown>>(
-    input: Array<Decrypted<T>>,
-    table: ProtectTable<ProtectTableColumn>,
-  ): BulkEncryptModelsOperation<T> {
-    return new BulkEncryptModelsOperation(this.client, input, table)
+  bulkEncryptModels<T extends Record<string, unknown>, S extends ProtectTableColumn = ProtectTableColumn>(
+    input: Array<T>,
+    table: ProtectTable<S>,
+  ): BulkEncryptModelsOperation<EncryptedFromSchema<T, S>> {
+    return new BulkEncryptModelsOperation(this.client, input as Array<Record<string, unknown>>, table)
   }
 
   /**