@microsoft/rayfin-guide 1.36.0-alpha.1593 → 1.36.0-alpha.1620

package/assets/docs/cli/secrets.md

@@ -4,193 +4,168 @@ 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.
+Secrets are encrypted values — API keys, connection strings, tokens — that your app needs at runtime but must never ship in client code. They are stored securely on your deployed Rayfin item and read on the server by [functions](./functions/index.md) via `ctx.getSecret(name)`.
 
-## Overview
+Manage secrets with the `npx rayfin secret` command group:
 
-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.
+| Command                                   | Description                                          |
+| ----------------------------------------- | ---------------------------------------------------- |
+| `npx rayfin secret set <name>`            | Set one secret (masked prompt or `--stdin`).         |
+| `npx rayfin secret set --env-file <path>` | Bulk-set every `KEY=VALUE` entry from a dotenv file. |
+| `npx rayfin secret list`                  | List secret names and timestamps (never values).     |
+| `npx rayfin secret delete <name>`         | Delete a secret.                                     |
 
-## Setting up secrets
+## Prerequisite: deploy first
 
-### 1. Define secrets in `.env`
-
-Create a `rayfin/.env` file with secrets prefixed using `RAYFIN_SECRET_`:
+Secrets live on the remote Rayfin item, so you must deploy before managing them:
 
 ```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
+npx rayfin up
 ```
 
-> **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`.
+Every `secret` command resolves the remote endpoint from your active deployment. If none exists, the CLI stops with:
+
+```text
+❌ No remote endpoint configured
+   Run 'npx rayfin up' first to deploy your item to Fabric.
+```
 
-### 2. Deploy your item
+## Setting a secret
 
-Before managing secrets, deploy your project to Microsoft Fabric:
+By default, `secret set` prompts for the value with masked input:
 
 ```bash
-npx rayfin up
+npx rayfin secret set OPENAI_KEY
+# ? Enter secret value for "OPENAI_KEY" ********
 ```
 
-This creates your Rayfin item and sets up the workload endpoint.
-
-### 3. Apply secrets
-
-Apply your secrets to the remote workload:
+For non-interactive use (CI, scripts), pipe the value in with `--stdin`:
 
 ```bash
-npx rayfin up secrets apply
+echo "sk-openai-your-key-here" | npx rayfin secret set OPENAI_KEY --stdin
 ```
 
-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
+### Recording a description in `rayfin.yml`
 
-After running the apply command, you'll see output confirming each secret:
+Use `--describe` to record a human-readable description alongside the secret's metadata in `rayfin/rayfin.yml` (the value itself is never written to `rayfin.yml`). The flag **must** use the `=` syntax:
 
-```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
+```bash
+npx rayfin secret set OPENAI_KEY --describe="OpenAI API key for the chat function"
 ```
 
-## Advanced usage
+Passing `--describe "..."` with a space is rejected — always use `--describe="..."`.
 
-### Custom .env file location
+## Bulk-setting from a file
 
-If your secrets are in a non-standard location, use the `--env-file` option:
+To set many secrets at once, keep them in a dotenv file and point `secret set` at it with `--env-file`:
 
 ```bash
-npx rayfin up secrets apply --env-file ./config/secrets.env
+# rayfin/.env.secrets
+OPENAI_KEY=sk-openai-your-key-here
+DATABASE_PASSWORD=secure-db-pass-123
+AUTH_TOKEN=token-abcdefg-hijklmn
 ```
 
-### JSON output
-
-For automation or scripting, use `--json` for machine-readable output:
-
 ```bash
-npx rayfin up secrets apply --json
+npx rayfin secret set --env-file rayfin/.env.secrets
 ```
 
-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"
-    }
-  ]
-}
-```
+Every `KEY=VALUE` line becomes a secret named `KEY` — there is **no prefix convention**; the key is used verbatim. Blank lines and `#` comments are ignored, and surrounding single or double quotes are stripped from values. Do not pass a `<name>` together with `--env-file`, and do not combine `--env-file` with `--stdin`.
 
-### Verbose logging
+> **Keep secret files out of version control.** Add your secrets file to `.gitignore` — it is for authoring only, never committed:
+>
+> ```bash
+> echo "rayfin/.env.secrets" >> .gitignore
+> ```
 
-Enable detailed logging for debugging:
+## Listing secrets
 
 ```bash
-npx rayfin up secrets apply --verbose
+npx rayfin secret list
 ```
 
-### Non-interactive mode
+Only names and created/updated timestamps are returned — values are never read back:
 
-Use `-y` or `--yes` to skip confirmation prompts:
+```text
+📋 Secrets (3):
 
-```bash
-npx rayfin up secrets apply -y
+  Name:         OPENAI_KEY
+  Created:      4/17/2026, 10:30:00 AM
+  Last Updated: 4/17/2026, 10:30:00 AM
 ```
 
-## Secret handling and security
+## Deleting a secret
 
-### Encryption
+```bash
+npx rayfin secret delete OPENAI_KEY          # prompts for confirmation
+npx rayfin secret delete OPENAI_KEY --yes    # skips the prompt (-y)
+```
 
-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.
+Deleting a secret that does not exist reports a not-found error — run `npx rayfin secret list` to see what is currently stored.
 
-### Best practices
+## Reading secrets from functions
 
-1. **Use `.env` files for local development only** – Never commit `.env` files to version control.
-   Add `.env` to your `.gitignore`:
+Server-side functions read secrets at runtime with `ctx.getSecret(name)`, which resolves against the deployed item's secret bag and falls back to `process.env`. Set a secret with `npx rayfin secret set <name>`, then read it by the same name inside your handler:
 
-   ```bash
-   echo "rayfin/.env" >> .gitignore
-   ```
+```ts
+udf.func("summarize", async (ctx, input: { text: string }) => {
+  const apiKey = ctx.getSecret("OPENAI_KEY");
+  // ... call the API with apiKey
+});
+```
 
-2. **Use environment variables for CI/CD** – In automated environments, set `RAYFIN_SECRET_*` variables directly:
+## Using secrets in local development
 
-   ```bash
-   export RAYFIN_SECRET_API_KEY=prod-key-from-vault
-   npx rayfin up secrets apply
-   ```
+When you run functions locally with [`npx rayfin dev functions apply`](./functions/dev-apply.md), there is no deployed secret bag, so `ctx.getSecret(name)` falls back to `process.env`. To make a secret available locally, add it under `Values` in `rayfin/functions/local.settings.json` — the Azure Functions host loads those entries into `process.env`:
 
-3. **Rotate secrets regularly** – Re-run `rayfin up secrets apply` after updating secret values in your `.env` file.
+```json
+{
+  "IsEncrypted": false,
+  "Values": {
+    "OPENAI_KEY": "sk-local-dev-key"
+  }
+}
+```
 
-4. **Separate development and production secrets** – Use different `.env` files or environment variables for each environment.
+`npx rayfin dev functions apply` **merges** its own CLI-managed values into `local.settings.json` and preserves any keys you add, so your local secrets survive re-runs. Keep `local.settings.json` out of version control — it is for local development only.
 
-## Troubleshooting
+## Automation and JSON output
 
-### No secrets found
+Every `secret` command accepts the global `--json` flag for machine-readable output and `--verbose` for detailed logging:
+
+```bash
+npx rayfin secret list --json
+npx rayfin secret set OPENAI_KEY --stdin --json < key.txt
+```
 
-If you see "No secrets found in .env file", verify:
+## Security notes
 
-- Your `.env` file exists at `rayfin/.env`
-- Variables are prefixed with `RAYFIN_SECRET_`
-- The file is readable by the CLI process
+- Secrets are transmitted over HTTPS and encrypted at rest on the workload. They are never logged or displayed after being sent.
+- `npx rayfin secret list` returns only names and timestamps — never values.
+- Use separate secret values per environment, and rotate them by re-running `npx rayfin secret set` with the new value.
 
-### Authentication failed
+## Troubleshooting
 
-If you see "Failed to acquire authentication token":
+### No remote endpoint configured
 
-- 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`
+Run `npx rayfin up` first to deploy your item, then retry. Secrets cannot be managed before an initial deployment exists.
 
-### Validation inconclusive
+### Authentication failed
 
-If some secrets fail validation:
+If acquiring a token fails:
 
-- 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
+- Run `npx rayfin login` to sign in and confirm you have valid Entra ID credentials.
+- On containers or restricted environments without an OS keychain, pass `--encryption-fallback-enabled` to allow plaintext token storage.
 
-### Permission denied
+### Secret not found on delete
 
-If you see permission errors:
+If `secret delete` reports the secret was not found:
 
-- 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
+- It may already be deleted — run `npx rayfin secret list` to confirm.
+- Secret management may not be enabled for the item; verify the deployment with `npx rayfin up status`.
 
 ## See also
 
+- [Functions](./functions/index.md) — read secrets from server-side functions with `ctx.getSecret`.
 - [CLI quickstart](./quickstart.md)
 - [Environment configuration](./env-interpolation.md)

package/assets/docs/cli/templates.md

@@ -20,6 +20,13 @@ Every `npm create @microsoft/rayfin@latest` or `npx rayfin init` invocation can
 External and local template sources are discovered through `rayfin-template.yml` manifests inside the selected source directory.
 Built-in templates are packaged with the CLI and appear in `--list-templates` automatically.
 
+> **Universal App is distributed by the Rayfin Copilot plugin.**
+> It is a hidden built-in template: it does not appear in `--list-templates`,
+> but it can be selected explicitly with `--template universal-app`.
+> The plugin selects that bundled template and distributes its committed workspace
+> template directly.
+> This does not change support for ordinary local directories, git repositories, or registered templates.
+
 ## List available templates
 
 Use `--list-templates` to see every template the CLI can scaffold from in your current directory:

package/assets/docs/functions/connections/add-ado.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 5
+---
+
+# Add Azure DevOps
+
+Call the [Azure DevOps REST API](https://learn.microsoft.com/en-us/rest/api/azure/devops/) from a function **as the signed-in user**, using `AudienceType.ADO`.
+
+Provide your Azure DevOps **organization** (and project, if the call needs one) — e.g. `https://dev.azure.com/<org>`. The token is a standard bearer token — send it with `fetch`:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+// Use your real organization URL.
+const ORG = "https://dev.azure.com/<org>";
+
+udf.func(
+  "listProjects",
+  async (ctx: RayfinContext): Promise<unknown> => {
+    const token = ctx.getToken(AudienceType.ADO);
+    const res = await fetch(`${ORG}/_apis/projects?api-version=7.1`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      throw new Error(`Azure DevOps returned ${res.status}`);
+    }
+    return res.json();
+  },
+  [udf.connection({ audienceType: AudienceType.ADO })],
+);
+```
+
+See [Connecting to external resources](./index.md) for the shared connection model.

package/assets/docs/functions/connections/add-azure-resource.md

@@ -0,0 +1,171 @@
+---
+sidebar_position: 3
+---
+
+# Add an Azure resource
+
+Connect a function to an **Azure service** — Key Vault, Cosmos DB, Blob Storage, or Event Grid — and call it **as the signed-in user**.
+
+These are Azure resources, not Fabric items, so their endpoints come from the **Azure portal** (there is no Fabric lookup). Each pattern declares the connection, reads the token with `ctx.getToken()`, and wraps it with the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper for the Azure SDK. See [Connecting to external resources](./index.md) for the shared model.
+
+## Key Vault
+
+Read secrets from Azure Key Vault using `AudienceType.KeyVault`.
+
+```bash
+cd rayfin/functions
+npm install @azure/keyvault-secrets @azure/identity
+```
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import { SecretClient } from "@azure/keyvault-secrets";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "getVaultSecret",
+  async (
+    ctx: RayfinContext,
+    kvUrl: string,
+    secretName: string,
+  ): Promise<string> => {
+    const credential = new ContextTokenCredential(
+      ctx.getToken(AudienceType.KeyVault),
+    );
+    const client = new SecretClient(kvUrl, credential);
+    const secret = await client.getSecret(secretName);
+    return secret.value ?? "";
+  },
+  [udf.connection({ audienceType: AudienceType.KeyVault })],
+);
+```
+
+Provide the vault URL (e.g. `https://my-vault.vault.azure.net/`).
+
+> To read secrets stored with Rayfin itself (rather than an external Key Vault), use [`ctx.getSecret()`](../secrets.md) instead — no connection required.
+
+## Cosmos DB
+
+Connect to Azure Cosmos DB using `AudienceType.CosmosDB`. Pass the credential as `aadCredentials`:
+
+```bash
+cd rayfin/functions
+npm install @azure/cosmos
+```
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import { CosmosClient } from "@azure/cosmos";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "readItems",
+  async (
+    ctx: RayfinContext,
+    endpoint: string,
+    databaseId: string,
+    containerId: string,
+  ): Promise<unknown[]> => {
+    const credential = new ContextTokenCredential(
+      ctx.getToken(AudienceType.CosmosDB),
+    );
+    const client = new CosmosClient({ endpoint, aadCredentials: credential });
+    const { resources } = await client
+      .database(databaseId)
+      .container(containerId)
+      .items.readAll()
+      .fetchAll();
+    return resources;
+  },
+  [udf.connection({ audienceType: AudienceType.CosmosDB })],
+);
+```
+
+Provide the account endpoint and the database / container names.
+
+## Blob Storage
+
+Connect to Azure Blob / Table / Queue storage using `AudienceType.Storage`:
+
+```bash
+cd rayfin/functions
+npm install @azure/storage-blob
+```
+
+```ts
+import { BlobServiceClient } from "@azure/storage-blob";
+
+udf.func(
+  "listBlobs",
+  async (ctx: RayfinContext, accountUrl: string): Promise<string[]> => {
+    const credential = new ContextTokenCredential(
+      ctx.getToken(AudienceType.Storage),
+    );
+    const service = new BlobServiceClient(accountUrl, credential);
+    const names: string[] = [];
+    for await (const container of service.listContainers()) {
+      names.push(container.name);
+    }
+    return names;
+  },
+  [udf.connection({ audienceType: AudienceType.Storage })],
+);
+```
+
+Provide the storage account URL (e.g. `https://<account>.blob.core.windows.net`).
+
+> `AudienceType.Storage` also covers **OneLake** files — that Fabric case is documented in [Add a Fabric resource → OneLake files](./add-fabric-resource.md#onelake-files).
+
+## Event Grid
+
+Publish events to an Azure Event Grid topic using `AudienceType.EventGrid`. The topic endpoint is in the Azure portal → your topic → **Overview** → _Topic Endpoint_.
+
+```bash
+cd rayfin/functions
+npm install @azure/eventgrid
+```
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import { EventGridPublisherClient } from "@azure/eventgrid";
+
+const udf = new UserDataFunctions();
+
+const TOPIC_ENDPOINT =
+  "https://<topic>.<region>.eventgrid.azure.net/api/events";
+
+udf.func(
+  "publishEvent",
+  async (ctx: RayfinContext, subject: string): Promise<string> => {
+    const client = new EventGridPublisherClient(
+      TOPIC_ENDPOINT,
+      "EventGrid",
+      new ContextTokenCredential(ctx.getToken(AudienceType.EventGrid)),
+    );
+    await client.send([
+      {
+        eventType: "Rayfin.Function.Event",
+        subject,
+        dataVersion: "1.0",
+        data: { source: "user-data-function" },
+      },
+    ]);
+    return "published";
+  },
+  [udf.connection({ audienceType: AudienceType.EventGrid })],
+);
+```