Merge pull request #568 from cipherstash/chore/bump-auth-0.41

Bump @cipherstash/auth to 0.41 and migrate to Result API

Author: coderdan

.changeset/stack-auth-0-41-result-api.md

@@ -0,0 +1,17 @@
+---
+"@cipherstash/stack": minor
+"@cipherstash/wizard": patch
+"stash": patch
+---
+
+Bump `@cipherstash/auth` (and its per-platform native bindings) from `0.40.0` to `0.41.0`, and migrate to its new `Result`-returning API.
+
+**What changed in `@cipherstash/auth` `0.41`.** Every fallible auth operation now returns a `@byteslice/result` `Result<T, AuthFailure>` (`{ data }` on success, `{ failure }` on error) instead of throwing. This covers strategy construction (`AccessKeyStrategy.create`, `OidcFederationStrategy.create`, `AutoStrategy.detect`, `DeviceSessionStrategy.fromProfile`), `getToken()`, and the device-code flow (`beginDeviceCodeFlow`, `pollForToken`, `openInBrowser`, `bindClientDevice`). Consumers now write `if (result.failure) …` and read `result.data` rather than `try/catch`. The `AuthError` type was renamed to **`AuthFailure`** — a discriminated union keyed by `type` (`"NOT_AUTHENTICATED"`, `"WORKSPACE_MISMATCH"`, …), replacing the old `error.code` string.
+
+**`@cipherstash/stack` (breaking type surface).**
+
+- **`AuthError` is renamed to `AuthFailure`** in the public re-exports from `@cipherstash/stack`. `AuthErrorCode` and `TokenResult` are unchanged. Anyone importing `AuthError` from `@cipherstash/stack` must switch to `AuthFailure`.
+- The WASM-inline access-key path (`resolveStrategy`, used by `@cipherstash/stack/wasm-inline`'s `Encryption()`) now unwraps the `Result` from `AccessKeyStrategy.create`. A construction failure (e.g. an invalid CRN or access key) throws a descriptive `[encryption]` error naming the `AuthFailure.type` instead of surfacing the raw auth error.
+- Bump `@cipherstash/protect-ffi` from `0.27.0` to `0.28.0`. auth `0.41`'s `getToken()` returns the token inside a `Result` envelope; protect-ffi `0.28` unwraps it (`.data.token`) inside its WASM `newClient`, whereas `0.27` read `.token` off the envelope and got `undefined` — which failed the WASM encrypt/decrypt round-trip with `token field is not a string`. `0.28` is the floor for the WASM path under auth `0.41`.
+
+**`stash` (CLI) and `@cipherstash/wizard`.** Internal auth call sites (`stash auth login`, device binding, `init` auth check, and the wizard's token acquisition / prerequisite check) were updated to unwrap `Result` and branch on `failure.type`. Behaviour is preserved — auth failures still surface the same way to end users; no CLI/wizard API changed.

e2e/wasm/deno.json

@@ -1,6 +1,6 @@
 {
   "//1": "Deno smoke test for @cipherstash/stack/wasm-inline. Run `pnpm exec turbo run build --filter @cipherstash/stack` first so dist/ is fresh.",
-  "//2": "stack is imported via a file URL because the wasm-inline subpath isn't on a published version yet — once stack ships with /wasm-inline this can switch to a plain npm: specifier. protect-ffi and auth resolve via npm: against the workspace's installed versions (Deno's nodeModulesDir: auto lets it use what pnpm fetched).",
+  "//2": "Everything resolves to files pnpm already installed in the workspace — no `npm:` specifiers, so Deno never re-resolves against the registry. stack is its locally-built dist; auth and protect-ffi are the WASM-inline entries of the exact versions the catalog pinned, reached via stack's own node_modules symlink (`packages/stack/node_modules/@cipherstash/*`). Both entries import only their own relative wasm bindings, so there are no transitive npm deps to resolve. This keeps the versions in lockstep with the catalog automatically (a bump to pnpm-workspace.yaml needs no edit here) and sidesteps Deno 2.9's default 24h npm freshness cooldown, which would otherwise reject a just-published first-party version and block lockstep bumps for a day. The real supply-chain gate is pnpm's `minimumReleaseAge` (see skills/stash-supply-chain-security/), which already exempts first-party @cipherstash packages.",
   "//3": "No --allow-ffi grant. If protect-ffi ever silently fell back to a native binding under Deno, the test would fail on missing FFI permission — this is the WASM guarantee.",
   "nodeModulesDir": "auto",
   "tasks": {
@@ -9,7 +9,7 @@
   },
   "imports": {
     "@cipherstash/stack/wasm-inline": "../../packages/stack/dist/wasm-inline.js",
-    "@cipherstash/protect-ffi/wasm-inline": "npm:@cipherstash/protect-ffi@0.26.0/wasm-inline",
-    "@cipherstash/auth/wasm-inline": "npm:@cipherstash/auth@0.40.0/wasm-inline"
+    "@cipherstash/protect-ffi/wasm-inline": "../../packages/stack/node_modules/@cipherstash/protect-ffi/dist/wasm/protect_ffi_inline.js",
+    "@cipherstash/auth/wasm-inline": "../../packages/stack/node_modules/@cipherstash/auth/wasm-inline.mjs"
   }
 }

packages/cli/src/commands/auth/login.ts

@@ -34,36 +34,49 @@ export async function login(region: string, _referrer: string | undefined) {
 
   // Must be 'cli' — it's the only OAuth client_id registered with CTS.
   // Passing anything else (e.g. `cli-supabase`) causes INVALID_CLIENT.
+  // As of `@cipherstash/auth` `0.41`, the device-code flow returns
+  // `Result<T, AuthFailure>` instead of throwing — unwrap each step.
   const pending = await beginDeviceCodeFlow(region, 'cli')
+  if (pending.failure) {
+    p.log.error(pending.failure.error.message)
+    process.exit(1)
+  }
+  const flow = pending.data
 
-  p.log.info(`Your code is: ${pending.userCode}`)
-  p.log.info(`Visit: ${pending.verificationUriComplete}`)
-  p.log.info(`Code expires in: ${pending.expiresIn}s`)
+  p.log.info(`Your code is: ${flow.userCode}`)
+  p.log.info(`Visit: ${flow.verificationUriComplete}`)
+  p.log.info(`Code expires in: ${flow.expiresIn}s`)
 
-  const opened = pending.openInBrowser()
-  if (!opened) {
+  const opened = flow.openInBrowser()
+  if (opened.failure || !opened.data) {
     p.log.warn('Could not open browser — please visit the URL above manually.')
   }
 
   s.start('Waiting for authorization...')
-  const auth = await pending.pollForToken()
+  const auth = await flow.pollForToken()
+  if (auth.failure) {
+    s.stop('Authentication failed!')
+    p.log.error(auth.failure.error.message)
+    process.exit(1)
+  }
   s.stop('Authenticated!')
 
   p.log.info(
-    `Token expires at: ${new Date(auth.expiresAt * 1000).toISOString()}`,
+    `Token expires at: ${new Date(auth.data.expiresAt * 1000).toISOString()}`,
   )
 }
 
 export async function bindDevice() {
   const s = p.spinner()
   s.start('Binding device to the default Keyset...')
 
-  try {
-    await bindClientDevice()
-    s.stop('Your device has been bound to the default Keyset!')
-  } catch (error) {
+  // `bindClientDevice()` returns `Result<void, AuthFailure>` as of
+  // `@cipherstash/auth` `0.41` — a failure no longer throws.
+  const result = await bindClientDevice()
+  if (result.failure) {
     s.stop('Failed to bind your device to the default Keyset!')
-    p.log.error(error instanceof Error ? error.message : 'Unknown error')
+    p.log.error(result.failure.error.message)
     process.exit(1)
   }
+  s.stop('Your device has been bound to the default Keyset!')
 }

packages/cli/src/commands/init/steps/authenticate.ts

@@ -16,13 +16,20 @@ interface ExistingAuth {
  */
 async function checkExistingAuth(): Promise<ExistingAuth | undefined> {
   try {
-    const strategy = AutoStrategy.detect()
-    const result = await strategy.getToken()
+    // As of `@cipherstash/auth` `0.41`, `detect()` and `getToken()` return a
+    // `Result<T, AuthFailure>` instead of throwing — a failure at either step
+    // just means "not authenticated yet", so fall through to `undefined`.
+    const detected = AutoStrategy.detect()
+    if (detected.failure) return undefined
 
-    const regionEntry = regions.find((r) => result.issuer.includes(r.value))
+    const result = await detected.data.getToken()
+    if (result.failure) return undefined
+
+    const { issuer, workspaceId } = result.data
+    const regionEntry = regions.find((r) => issuer.includes(r.value))
     const regionLabel = regionEntry?.label ?? 'unknown'
 
-    return { workspace: result.workspaceId, regionLabel }
+    return { workspace: workspaceId, regionLabel }
   } catch {
     return undefined
   }

packages/stack/__tests__/helpers/stub-auth-wasm-inline.ts

@@ -6,6 +6,10 @@
  * lets Vitest load `src/wasm-inline` for pure-helper unit tests. Aliased in via
  * `vitest.config.ts`.
  */
+// `@cipherstash/auth` `0.41` `create` returns a `Result<Strategy, AuthFailure>`
+// rather than throwing. These stubs are only reached by tests that don't
+// override the module with `vi.mock`; they still throw loudly so an
+// unexpectedly-exercised path fails visibly rather than silently.
 export const AccessKeyStrategy = {
   create: (): never => {
     throw new Error(

packages/stack/__tests__/init-strategy.test.ts

@@ -165,6 +165,20 @@ describe('Encryption config.strategy (deprecated alias)', () => {
 
     expect(warnSpy).not.toHaveBeenCalled()
   })
+
+  it('warns at most once per process across repeated Encryption calls', async () => {
+    // No reset between the two calls (the latch is only reset in beforeEach),
+    // so they share one process-level latch — a regression that dropped the
+    // `if (warnedStrategyDeprecated) return` guard would warn twice here.
+    const strategy: AuthStrategy = {
+      getToken: vi.fn(async () => ({ token: 'service-token' })),
+    }
+
+    await Encryption({ schemas: [users], config: { strategy } })
+    await Encryption({ schemas: [users], config: { strategy } })
+
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+  })
 })
 
 // A minimal structural EQL v3 table: what marks a table as v3 for wire-format

packages/stack/__tests__/wasm-inline-new-client.test.ts

@@ -18,7 +18,9 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('@cipherstash/auth/wasm-inline', () => ({
   AccessKeyStrategy: {
-    create: vi.fn(() => ({ __mock: 'access-key-strategy' })),
+    // `@cipherstash/auth` `0.41` `create` returns a `Result<Strategy, AuthFailure>`
+    // (`{ data }` on success) — `resolveStrategy` unwraps `.data`.
+    create: vi.fn(() => ({ data: { __mock: 'access-key-strategy' } })),
   },
   OidcFederationStrategy: class {},
 }))

packages/stack/__tests__/wasm-inline-strategy.test.ts

@@ -17,7 +17,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('@cipherstash/auth/wasm-inline', () => ({
   AccessKeyStrategy: {
-    create: vi.fn(() => ({ __mock: 'access-key-strategy' })),
+    // `@cipherstash/auth` `0.41` `create` returns a `Result<Strategy, AuthFailure>`
+    // (`{ data }` on success) — `resolveStrategy` unwraps `.data`.
+    create: vi.fn(() => ({ data: { __mock: 'access-key-strategy' } })),
   },
   OidcFederationStrategy: class {},
 }))
@@ -65,6 +67,35 @@ describe('wasm-inline resolveStrategy', () => {
     expect(warnSpy).not.toHaveBeenCalled()
   })
 
+  it('throws when AccessKeyStrategy.create returns a failure Result', () => {
+    // `@cipherstash/auth` `0.41` `create` returns `{ failure }` instead of
+    // throwing — `resolveStrategy` must surface that as a loud construction
+    // error naming the failure type and the underlying message, not forward
+    // an unusable strategy.
+    vi.mocked(AccessKeyStrategy.create).mockReturnValueOnce(
+      // biome-ignore lint/suspicious/noExplicitAny: mock the 0.41 Result failure arm
+      {
+        failure: {
+          type: 'InvalidWorkspaceCrn',
+          error: new Error('unparseable CRN'),
+        },
+      } as any,
+    )
+
+    expect(() =>
+      // biome-ignore lint/suspicious/noExplicitAny: exercise the access-key arm directly
+      resolveStrategy({ workspaceCrn: CRN, accessKey: 'CSAK.test' } as any),
+    ).toThrowError(
+      /failed to construct.*\(InvalidWorkspaceCrn\): unparseable CRN/,
+    )
+    // The guards passed and it reached the builder before failing.
+    expect(vi.mocked(AccessKeyStrategy.create)).toHaveBeenCalledWith(
+      CRN,
+      'CSAK.test',
+    )
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
   it('uses an explicit config.authStrategy verbatim and never builds an access key', () => {
     const explicit = { getToken: vi.fn() }
     // biome-ignore lint/suspicious/noExplicitAny: exercise the authStrategy arm of the discriminated union directly
@@ -87,6 +118,19 @@ describe('wasm-inline resolveStrategy', () => {
     )
   })
 
+  it('warns at most once per process across repeated resolveStrategy calls', () => {
+    // No reset between the two calls (the latch is only reset in beforeEach),
+    // so they share one process-level latch — a regression that dropped the
+    // `if (warnedStrategyDeprecated) return` guard would warn twice here.
+    const explicit = { getToken: vi.fn() }
+    // biome-ignore lint/suspicious/noExplicitAny: exercise the deprecated strategy arm directly
+    resolveStrategy({ strategy: explicit } as any)
+    // biome-ignore lint/suspicious/noExplicitAny: exercise the deprecated strategy arm directly
+    resolveStrategy({ strategy: explicit } as any)
+
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+  })
+
   it('prefers authStrategy over the deprecated strategy when both are set, and still warns', () => {
     const authStrategy = { getToken: vi.fn() }
     const strategy = { getToken: vi.fn() }

packages/stack/package.json

@@ -244,7 +244,7 @@
 	"dependencies": {
 		"@byteslice/result": "0.2.0",
 		"@cipherstash/auth": "catalog:repo",
-		"@cipherstash/protect-ffi": "0.27.0",
+		"@cipherstash/protect-ffi": "0.28.0",
 		"evlog": "1.11.0",
 		"uuid": "14.0.0",
 		"zod": "3.25.76"

packages/stack/src/index.ts

@@ -36,6 +36,10 @@ export type OidcFederationStrategy = InstanceType<
   typeof auth.OidcFederationStrategy
 >
 
-export type { AuthError, AuthErrorCode, TokenResult } from '@cipherstash/auth'
+export type {
+  AuthErrorCode,
+  AuthFailure,
+  TokenResult,
+} from '@cipherstash/auth'
 // Re-export types for convenience
 export type { Encrypted } from '@/types'