@microsoft/rayfin-guide 1.34.0-alpha.1148 → 1.34.0-alpha.1201

package/assets/docs/auth/overview.md

@@ -12,7 +12,9 @@ This guide explains how to configure Rayfin authentication in your application.
 - **Token management** - Access tokens never exposed to application code.
 - **Session Management** - Automatic state tracking with localStorage, sessionStorage, or custom storage.
 - **Event System** - React-friendly session change notifications.
-- **Server-side Compatible** - Works in Node.js with custom storage.
+- **Isomorphic** - Works in Node.js, React Native, and Electron without crashing.
+  The constructor auto-detects the runtime and skips browser APIs when `window` is undefined.
+- **Async Storage** - Storage adapters can return promises for async backends (e.g., React Native AsyncStorage).
 
 ## Auth client API surface
 
@@ -23,7 +25,9 @@ The auth client exposes the following methods for sign-up, sign-in, session mana
 | `signUp({ email, password })` | Register a new user. |
 | `signIn({ email, password })` | Authenticate an existing user. |
 | `signOut()` | End the current session. |
-| `getSession()` | Return the current session (opaque; check `isAuthenticated` or `user`). |
+| `getSession()` | Return the current session (async; check `isAuthenticated` or `user`). |
+| `startAutoRefresh()` | Resume automatic token refresh (for React Native / manual control). |
+| `stopAutoRefresh()` | Pause automatic token refresh. |
 | `onSessionChange(callback)` | Subscribe to session state changes; returns an unsubscribe function. |
 
 > **Important**
@@ -114,11 +118,15 @@ That hook keeps React in sync with the Rayfin auth session.
 ```typescript
 import { useState, useEffect } from 'react';
 import { auth } from './lib/rayfin';
+import type { OpaqueSession } from '@microsoft/rayfin-auth';
 
 export function useAuth() {
-  const [session, setSession] = useState(auth.getSession());
+  const [session, setSession] = useState<OpaqueSession | null>(null);
 
-  useEffect(() => auth.onSessionChange(setSession), []);
+  useEffect(() => {
+    setSession(auth.getSession());
+    return auth.onSessionChange(setSession);
+  }, []);
 
   return {
     ...session,

package/assets/docs/cli/index.md

@@ -52,6 +52,7 @@ For the full walkthrough, see the [CLI Quickstart](./quickstart.md) or the [Buil
 | `npx rayfin up` | Deploy the project to Microsoft Fabric. If you are not signed in, the CLI launches an interactive login flow. Use `-t, --tenant <id>` when your account spans multiple tenants, `-w, --workspace <name>` for a Fabric workspace display name, `-n, --dry-run` to preview without API calls, and `-v, --verbose` for detailed output. Pass `--encryption-fallback-enabled` only when login fails with a keychain error to allow plaintext token storage on systems without OS credential storage, such as some Linux distros, dev containers, and Codespaces. Use `--exclude-services staticHosting` to skip static content build/package/deploy while leaving runtime settings untouched — useful during local development when Vite serves the frontend. Applies runtime settings, database configuration, and static content when enabled. |
 | `npx rayfin up status` | Display the status of the Fabric deployment (add `--json` for machine-readable output). |
 | `npx rayfin up db apply` | Generate and apply DAB configuration to the remote Rayfin item. Add `--force` to allow changes that may cause data loss. |
+| `npx rayfin up secrets apply` | Read secrets from `rayfin/.env` file (prefixed with `RAYFIN_SECRET_`) and securely apply them to the remote Rayfin item workload. Validates that secrets are persisted. Use `--env-file <path>` to specify a custom .env file location. |
 | `npx rayfin up staticapp deploy` | Build, package, and deploy static content to the remote Rayfin item. Add `--skip-build` to deploy existing build output without rebuilding. |
 
 ## Update the CLI

package/assets/docs/cli/secrets.md

@@ -0,0 +1,196 @@
+---
+sidebar_position: 50
+---
+
+# Managing Secrets
+
+The Rayfin CLI provides secure secret management for your remote deployments.
+Secrets are encrypted and stored securely in your Rayfin item workload.
+
+## Overview
+
+Use the `rayfin up secrets apply` command to manage application secrets for your remote deployment.
+Secrets are read from your `.env` file, securely transmitted to your workload, encrypted, and validated.
+
+## Setting up secrets
+
+### 1. Define secrets in `.env`
+
+Create a `rayfin/.env` file with secrets prefixed using `RAYFIN_SECRET_`:
+
+```bash
+# rayfin/.env
+RAYFIN_SECRET_API_KEY=sk-prod-abc123xyz789
+RAYFIN_SECRET_DATABASE_PASSWORD=secure-db-pass-123
+RAYFIN_SECRET_AUTH_TOKEN=token-abcdefg-hijklmn
+RAYFIN_SECRET_OPENAI_KEY=sk-openai-your-key-here
+```
+
+> **Secret naming:** Secret names must follow the `RAYFIN_SECRET_` prefix convention.
+> The part after the prefix becomes your secret name.
+> For example, `RAYFIN_SECRET_API_KEY` creates a secret named `API_KEY`.
+
+### 2. Deploy your item
+
+Before managing secrets, deploy your project to Microsoft Fabric:
+
+```bash
+npx rayfin up
+```
+
+This creates your Rayfin item and sets up the workload endpoint.
+
+### 3. Apply secrets
+
+Apply your secrets to the remote workload:
+
+```bash
+npx rayfin up secrets apply
+```
+
+The CLI will:
+1. Read your `rayfin/.env` file
+2. Extract all `RAYFIN_SECRET_*` variables
+3. Securely send each secret to your workload
+4. Encrypt and persist the secrets
+5. Validate that all secrets were successfully saved
+
+### 4. Verify secrets
+
+After running the apply command, you'll see output confirming each secret:
+
+```text
+🔐 Acquiring authentication token...
+✓ Token acquired
+📤 Sending 4 secret(s) to workload...
+✓ Secrets sent to workload (4 persisted)
+✅ Validating secrets persisted to workload...
+✓ All secrets validated
+
+✨ Secrets applied successfully (4/4)
+  ✓ API_KEY
+  ✓ DATABASE_PASSWORD
+  ✓ AUTH_TOKEN
+  ✓ OPENAI_KEY
+```
+
+## Advanced usage
+
+### Custom .env file location
+
+If your secrets are in a non-standard location, use the `--env-file` option:
+
+```bash
+npx rayfin up secrets apply --env-file ./config/secrets.env
+```
+
+### JSON output
+
+For automation or scripting, use `--json` for machine-readable output:
+
+```bash
+npx rayfin up secrets apply --json
+```
+
+Output example:
+
+```json
+{
+  "status": "success",
+  "message": "All secrets applied and validated",
+  "secretsCount": 4,
+  "persisted": 4,
+  "validated": true,
+  "secrets": [
+    {
+      "name": "API_KEY",
+      "id": "secret-123",
+      "createdAt": "2026-04-17T10:30:00Z"
+    }
+  ]
+}
+```
+
+### Verbose logging
+
+Enable detailed logging for debugging:
+
+```bash
+npx rayfin up secrets apply --verbose
+```
+
+### Non-interactive mode
+
+Use `-y` or `--yes` to skip confirmation prompts:
+
+```bash
+npx rayfin up secrets apply -y
+```
+
+## Secret handling and security
+
+### Encryption
+
+Secrets are transmitted over HTTPS with encrypted payloads.
+The workload endpoint encrypts and persists secrets securely.
+Secrets are never logged or displayed after being sent to the workload.
+
+### Best practices
+
+1. **Use `.env` files for local development only** – Never commit `.env` files to version control.
+   Add `.env` to your `.gitignore`:
+
+   ```bash
+   echo "rayfin/.env" >> .gitignore
+   ```
+
+2. **Use environment variables for CI/CD** – In automated environments, set `RAYFIN_SECRET_*` variables directly:
+
+   ```bash
+   export RAYFIN_SECRET_API_KEY=prod-key-from-vault
+   npx rayfin up secrets apply
+   ```
+
+3. **Rotate secrets regularly** – Re-run `rayfin up secrets apply` after updating secret values in your `.env` file.
+
+4. **Separate development and production secrets** – Use different `.env` files or environment variables for each environment.
+
+## Troubleshooting
+
+### No secrets found
+
+If you see "No secrets found in .env file", verify:
+
+- Your `.env` file exists at `rayfin/.env`
+- Variables are prefixed with `RAYFIN_SECRET_`
+- The file is readable by the CLI process
+
+### Authentication failed
+
+If you see "Failed to acquire authentication token":
+
+- Run `npx rayfin login` to sign in
+- Check that you have valid Entra ID credentials
+- On containers or restricted environments, use `--encryption-fallback-enabled` or set `RAYFIN_ENCRYPTION_FALLBACK_ENABLED=true`
+
+### Validation inconclusive
+
+If some secrets fail validation:
+
+- Check your network connection to Fabric
+- Verify the workload endpoint is running and healthy
+- Run `npx rayfin up status` to confirm deployment health
+- Re-run `npx rayfin up secrets apply` to retry
+
+### Permission denied
+
+If you see permission errors:
+
+- Ensure you're authenticated with an account that has access to the Fabric workspace
+- Verify you have the correct workspace selected
+- Run `npx rayfin login --select` to choose a different account/tenant
+
+## See also
+
+- [CLI quickstart](./quickstart.md)
+- [Environment configuration](./env-interpolation.md)

package/assets/docs/data/graphql.md

@@ -34,6 +34,9 @@ Rayfin's fluent client produces DAB-compliant GraphQL and returns typed entities
 The GraphQL fluent client is available as `client.data.<Entity>`.
 Some older examples may show `client.data.gql.<Entity>`.
 
+Required `@text()` fields return an empty string when the stored value is empty.
+Optional `@text({ optional: true })` fields preserve `null` so apps can distinguish an intentionally missing value from empty text.
+
 ### Read multiple records
 
 Here is an example to read records and order by a column.
@@ -259,7 +262,7 @@ const env = loadEnv();
 const client = new RayfinClient<AppSchema>({
   baseUrl: env['VITE_RAYFIN_API_URL'],
   publishableKey: env['VITE_RAYFIN_PUBLISHABLE_KEY'],
-  authStorage: false, // Required — Node.js has no localStorage
+  authStorage: false, // Optional — Node.js has no localStorage but Auth auto-detects
 });
 
 async function seed() {
@@ -295,7 +298,8 @@ Run with `npx tsx scripts/seed.ts`, or add `"seed": "npx tsx scripts/seed.ts"` t
 
 Key rules:
 
-- Set `authStorage: false` — Node.js has no `localStorage` and the client will crash without it.
+- Set `authStorage: false` — disables session persistence in Node.js scripts.
+  This is optional since Auth now auto-detects Node.js and falls back to memory-only storage, but explicit `false` makes intent clear.
 - Read `baseUrl` and `publishableKey` from `.env`, not hardcoded values — the port and key vary per project.
 - Email/password auth works for **local development seeding only**.
   Deployed Fabric apps use Entra SSO exclusively.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.34.0-alpha.1148",
+  "version": "1.34.0-alpha.1201",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [