@microsoft/rayfin-guide 1.36.0-alpha.1756 → 1.36.0-beta.0

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

@@ -4,11 +4,18 @@ sidebar_position: 2
 
 # Add a Fabric resource
 
-Connect a function to a **Microsoft Fabric item** — a Lakehouse, Warehouse, SQL Database, OneLake files, or an Eventhouse (KQL) — and call it **as the signed-in user**.
+Connect a deployed function to a **Microsoft Fabric item** — a Lakehouse, Warehouse, SQL Database, or OneLake files.
 
-**Before you start:** you need the item's coordinates (SQL endpoint, OneLake path, or Kusto query URI). See [Get Fabric info](./get-fabric-info.md) for how to pull them from the Fabric REST API.
+For the app's Rayfin DB, use [`ctx.getDataClient()`](../writing-functions.md#accessing-data-and-request-context) instead.
 
-All the patterns below follow the same model: declare the connection, read the token with `ctx.getToken()`, use it. See [Connecting to external resources](./index.md) for the shared model and the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper referenced here.
+Grant the [application identity](../index.md#application-authentication) the required access to the workspace, item, or database for the operation you need.
+
+**Before you start:** you need the item's coordinates (SQL endpoint or OneLake path).
+See [Get Fabric info](./get-fabric-info.md) for how to pull them from the Fabric REST API.
+
+All the patterns below follow the same model: declare the audience in the `RayfinContext` annotation, read the token from `ctx.Tokens`, use it. See [Connecting to external resources](./index.md) for the shared model and the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper referenced here.
+
+`AppSchema` below is your app's data schema — the same type you pass to `RayfinClient<AppSchema>`. See [Writing functions](../writing-functions.md#accessing-data-and-request-context).
 
 ## SQL databases
 
@@ -16,7 +23,7 @@ Covers Fabric **Lakehouse** (SQL analytics endpoint), **Warehouse**, **SQL Datab
 
 - **Package:** `mssql@^12.6.0` (which pulls `tedious >= 19.2.2`). Older `tedious` (`<= 19.1.2`) has a LOGIN7 FeatureExt bug that causes "socket hang up" errors against Fabric endpoints.
 - **Encryption:** `encrypt: true` (not `'strict'`). This matches ODBC `Encrypt=yes`.
-- **Auth:** `azure-active-directory-access-token` with the token from `ctx.getToken(AudienceType.Sql)`.
+- **Auth:** `azure-active-directory-access-token` with the token from `ctx.Tokens.Sql`.
 
 Install the driver in the functions project:
 
@@ -52,10 +59,10 @@ const DATABASE = "<item-guid-or-db-name>";
 udf.func(
   "queryData",
   async (
-    ctx: RayfinContext,
+    ctx: RayfinContext<AppSchema, AudienceType.Sql>,
     query: string,
   ): Promise<Record<string, unknown>[]> => {
-    const token = ctx.getToken(AudienceType.Sql);
+    const token = ctx.Tokens.Sql;
     const pool = await sql.connect({
       server: SQL_SERVER,
       database: DATABASE,
@@ -69,7 +76,7 @@ udf.func(
     await pool.close();
     return result.recordset;
   },
-  [udf.connection({ audienceType: AudienceType.Sql })],
+  [],
 );
 ```
 
@@ -79,7 +86,7 @@ Read and write files in a Lakehouse's OneLake storage using `AudienceType.Storag
 
 The OneLake DFS URL has the form `https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<itemId>/Files/<path>` — get it from `oneLakeFilesPath` via [Get Fabric info](./get-fabric-info.md#lakehouse), or construct it from the workspace and item GUIDs.
 
-Call the DFS endpoint directly with the delegated token — no SDK required:
+Call the DFS endpoint directly with the app-identity token — no SDK required:
 
 ```ts
 import {
@@ -92,8 +99,11 @@ const udf = new UserDataFunctions();
 
 udf.func(
   "readFile",
-  async (ctx: RayfinContext, fileUrl: string): Promise<string> => {
-    const token = ctx.getToken(AudienceType.Storage);
+  async (
+    ctx: RayfinContext<AppSchema, AudienceType.Storage>,
+    fileUrl: string,
+  ): Promise<string> => {
+    const token = ctx.Tokens.Storage;
     const res = await fetch(fileUrl, {
       headers: { Authorization: `Bearer ${token}` },
     });
@@ -102,59 +112,16 @@ udf.func(
     }
     return await res.text();
   },
-  [udf.connection({ audienceType: AudienceType.Storage })],
+  [],
 );
 ```
 
-## Eventhouse and KQL
-
-Query a Fabric **Eventhouse** (KQL database) or a standalone Azure Data Explorer cluster using `AudienceType.Kusto`.
-
-Get the cluster's **query URI** from the Eventhouse's `properties.queryServiceUri` — see [Get Fabric info → Eventhouse](./get-fabric-info.md#eventhouse).
-
-`azure-kusto-data` accepts a token provider, so hand it a callback that returns `ctx.getToken`:
-
-```ts
-import {
-  UserDataFunctions,
-  AudienceType,
-  type RayfinContext,
-} from "@microsoft/fabric-user-data-functions";
-import { Client, KustoConnectionStringBuilder } from "azure-kusto-data";
-
-const udf = new UserDataFunctions();
-
-// Read these from the Eventhouse item — see "Get Fabric info".
-const CLUSTER_URI = "https://<cluster>.z5.kusto.fabric.microsoft.com";
-const DATABASE = "<kql-database-name>";
-
-udf.func(
-  "queryKusto",
-  async (ctx: RayfinContext, query: string): Promise<unknown[]> => {
-    const kcsb = KustoConnectionStringBuilder.withTokenProvider(
-      CLUSTER_URI,
-      async () => ctx.getToken(AudienceType.Kusto),
-    );
-    const client = new Client(kcsb);
-    const response = await client.execute(DATABASE, query);
-    return response.primaryResults[0].toJSON().data;
-  },
-  [udf.connection({ audienceType: AudienceType.Kusto })],
-);
-```
-
-Install the SDK in the functions project:
-
-```bash
-cd rayfin/functions
-npm install azure-kusto-data
-```
-
 ## Fabric REST API
 
-Call the [Fabric REST API](https://learn.microsoft.com/en-us/rest/api/fabric/) as the calling user — for example to list items or read item metadata from inside a function — using `AudienceType.Fabric`.
+Call the [Fabric REST API](https://learn.microsoft.com/en-us/rest/api/fabric/) as the app identity — for example to list items or read item metadata from inside a function — using `AudienceType.Fabric`.
+Check that the specific API supports application identities and that the app identity has the required access.
 
-The API base is fixed at `https://api.fabric.microsoft.com/v1`; `ctx.getToken(AudienceType.Fabric)` returns a token scoped for it. Send it as a bearer token with `fetch`:
+The API base is fixed at `https://api.fabric.microsoft.com/v1`; `ctx.Tokens.Fabric` returns a token scoped for it. Send it as a bearer token with `fetch`:
 
 ```ts
 import {
@@ -169,8 +136,11 @@ const FABRIC_API = "https://api.fabric.microsoft.com/v1";
 
 udf.func(
   "listWorkspaceItems",
-  async (ctx: RayfinContext, workspaceId: string): Promise<unknown> => {
-    const token = ctx.getToken(AudienceType.Fabric);
+  async (
+    ctx: RayfinContext<AppSchema, AudienceType.Fabric>,
+    workspaceId: string,
+  ): Promise<unknown> => {
+    const token = ctx.Tokens.Fabric;
     const res = await fetch(`${FABRIC_API}/workspaces/${workspaceId}/items`, {
       headers: { Authorization: `Bearer ${token}` },
     });
@@ -179,8 +149,8 @@ udf.func(
     }
     return res.json();
   },
-  [udf.connection({ audienceType: AudienceType.Fabric })],
+  [],
 );
 ```
 
-> This is the same API used in [Get Fabric info](./get-fabric-info.md) — the difference is that there you call it at **authoring time** (with an `az` token) to gather endpoints, whereas here the **function** calls it at runtime with the user's delegated token.
+> This is the same API used in [Get Fabric info](./get-fabric-info.md) — the difference is that there you call it at **authoring time** (with an `az` token) to gather endpoints, whereas here the **deployed function** calls it at runtime with the app identity's token and resource permissions.

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

@@ -4,10 +4,14 @@ sidebar_position: 4
 
 # Add Azure AI Foundry
 
-Call an **Azure AI Foundry** (Azure OpenAI / Azure AI) resource from a function **as the signed-in user**, using `AudienceType.AzureAI`.
+Call an **Azure AI Foundry** (Azure OpenAI / Azure AI) resource from a deployed function using `AudienceType.AzureAI`.
+
+Grant the [application identity](../index.md#application-authentication) the permissions required by your Azure AI resource and API.
 
 Provide the resource **endpoint** (Azure AI Foundry → your resource → _Endpoint_). The token is a standard bearer token — send it with `fetch`, or wrap it with the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper for an Azure AI SDK client.
 
+`AppSchema` below is your app's data schema — the same type you pass to `RayfinClient<AppSchema>`. See [Writing functions](../writing-functions.md#accessing-data-and-request-context).
+
 ```ts
 import {
   UserDataFunctions,
@@ -22,8 +26,11 @@ const AI_ENDPOINT = "https://<resource>.services.ai.azure.com";
 
 udf.func(
   "callAzureAi",
-  async (ctx: RayfinContext, prompt: string): Promise<unknown> => {
-    const token = ctx.getToken(AudienceType.AzureAI);
+  async (
+    ctx: RayfinContext<AppSchema, AudienceType.AzureAI>,
+    prompt: string,
+  ): Promise<unknown> => {
+    const token = ctx.Tokens.AzureAI;
     const res = await fetch(`${AI_ENDPOINT}/...`, {
       method: "POST",
       headers: {
@@ -37,7 +44,7 @@ udf.func(
     }
     return res.json();
   },
-  [udf.connection({ audienceType: AudienceType.AzureAI })],
+  [],
 );
 ```
 

package/assets/docs/functions/connections/get-fabric-info.md

@@ -4,12 +4,14 @@ sidebar_position: 1
 
 # Finding resource coordinates
 
-Every connection recipe needs a real endpoint — the SQL server, the OneLake path, the Key Vault URI, the Kusto query URI, and so on.
+Every connection recipe needs a real endpoint, such as the SQL server or the OneLake path.
 This page explains **how to obtain those values from a Fabric item** so you (or an agent authoring a function) can fill them in with real data instead of guessing.
 
-**You only need the workspace and item _display names_ to start** — for example, "lakehouseA in workspaceB". Everything else (the workspace ID, item ID, SQL endpoint, OneLake path, Kusto URI) is derivable from here. Resolve those values rather than asking for anything you can look up.
+**You only need the workspace and item _display names_ to start** — for example, "lakehouseA in workspaceB".
+Everything else (the workspace ID, item ID, SQL endpoint, OneLake path) is derivable from here.
+Resolve those values rather than asking for anything you can look up.
 
-> **Why this matters:** don't hardcode a guessed endpoint. `ctx.getToken()` gives you an access token, but you still have to point the SDK at the correct URL — and that URL comes from the Fabric item's metadata, not from `process.env`.
+> **Why this matters:** don't hardcode a guessed endpoint. `ctx.Tokens` gives you an access token, but you still have to point the SDK at the correct URL — and that URL comes from the Fabric item's metadata, not from `process.env`.
 
 ## Ways to get coordinates
 
@@ -36,7 +38,7 @@ az account get-access-token \
   --query accessToken -o tsv
 ```
 
-> This is an **authoring-time** lookup — you are gathering coordinates to write into the function. At **runtime** the function itself uses `ctx.getToken(AudienceType.X)` (or, for the Fabric API specifically, `ctx.getToken(AudienceType.Fabric)` — see [Add a Fabric resource → Fabric REST API](./add-fabric-resource.md#fabric-rest-api)).
+> This is an **authoring-time** lookup — you are gathering coordinates to write into the function. At **runtime** the function itself declares the audience on its `RayfinContext` annotation and reads `ctx.Tokens.<Audience>` (for the Fabric API specifically, `ctx.Tokens.Fabric` — see [Add a Fabric resource → Fabric REST API](./add-fabric-resource.md#fabric-rest-api)).
 
 ## Step 1 — find the workspace and item ID
 
@@ -52,7 +54,7 @@ List items of a given type in a workspace (to resolve a display name to its ID):
 GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items?type=Lakehouse
 ```
 
-`type` accepts any Fabric item type — `Lakehouse`, `Warehouse`, `SQLDatabase`, `Eventhouse`, `KQLDatabase`, and so on.
+`type` accepts any Fabric item type — for these recipes, use `Lakehouse`, `Warehouse`, or `SQLDatabase`.
 Each entry returns `id`, `displayName`, and `type`. Take the `id` of the item you want.
 
 ## Step 2 — GET the item to read its coordinates
@@ -120,25 +122,6 @@ GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{s
 
 - **Server** → `properties.serverFqdn`, **database** → `properties.databaseName`. Both are also embedded in `properties.connectionString`.
 
-### Eventhouse
-
-```http
-GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/eventhouses/{eventhouseId}
-```
-
-```json
-{
-  "type": "Eventhouse",
-  "properties": {
-    "queryServiceUri": "https://xxxxx.z5.kusto.fabric.microsoft.com",
-    "ingestionServiceUri": "https://ingest-xxxxx.z5.kusto.fabric.microsoft.com",
-    "databasesItemIds": ["<kql-database-item-id>"]
-  }
-}
-```
-
-- **Cluster / query URI** → `properties.queryServiceUri`. Use with [Eventhouse and KQL](./add-fabric-resource.md#eventhouse-and-kql). Each KQL database inside the eventhouse is listed in `databasesItemIds`.
-
 ## Coordinate lookup table
 
 | You need                       | Item type    | Endpoint                | Field                                               |
@@ -147,7 +130,6 @@ GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/eventhouses/{ev
 | SQL server (Warehouse)         | Warehouse    | `.../warehouses/{id}`   | `properties.connectionString`                       |
 | SQL server + database (SQL DB) | SQL Database | `.../sqlDatabases/{id}` | `properties.serverFqdn` / `properties.databaseName` |
 | OneLake Files / Tables URL     | Lakehouse    | `.../lakehouses/{id}`   | `properties.oneLakeFilesPath` / `oneLakeTablesPath` |
-| Kusto query URI                | Eventhouse   | `.../eventhouses/{id}`  | `properties.queryServiceUri`                        |
 | Item GUID (any item)           | any          | `.../items?type={Type}` | `id`                                                |
 
 For item types not listed here, browse the [Fabric REST API item reference](https://learn.microsoft.com/en-us/rest/api/fabric/) — each item's **Get** operation returns its coordinates under `properties`.

package/assets/docs/functions/connections/index.md

@@ -4,12 +4,15 @@ sidebar_position: 5
 
 # Connecting to external resources
 
-Functions can call external Azure and Fabric resources **as the calling user** using delegated authentication.
-You declare a connection on the function, and at invocation time the runtime exchanges the user's identity for a resource-scoped on-behalf-of (OBO) token.
+Deployed Functions call external Azure and Fabric resources **as the app identity** using application authentication.
+You declare the audiences a function needs and consume platform-provided, resource-scoped tokens through `ctx.Tokens`.
+See [Application authentication](../index.md#application-authentication) for configuration, resource permissions, and the distinction from caller-scoped Rayfin DB access.
+
+Developer CLI login and authoring-time endpoint discovery are separate from deployed runtime access; verify the deployed app identity's permissions even when a developer can access the resource.
 
 ## The pattern
 
-Declare an audience-scoped connection in the third argument of `udf.func()`, then read its token with `ctx.getToken()`:
+Declare the audiences in the `RayfinContext` annotation, then read the scoped token off `ctx.Tokens`:
 
 ```ts
 import {
@@ -21,19 +24,123 @@ import {
 const udf = new UserDataFunctions();
 
 udf.func(
-  "myFunction",
-  async (ctx: RayfinContext): Promise<string> => {
-    const token = ctx.getToken(AudienceType.KeyVault);
+  "accessStorage",
+  async (
+    ctx: RayfinContext<AppSchema, AudienceType.Storage>,
+  ): Promise<string> => {
+    const token: string = ctx.Tokens.Storage;
     // Use `token` with the resource's SDK or REST API.
     return "ok";
   },
-  [udf.connection({ audienceType: AudienceType.KeyVault })],
+  [],
+);
+```
+
+**The annotation is the declaration.** Listing an audience in `RayfinContext<Schema, Audiences>` is what registers the connection binding — there is nothing to add to the third argument of `udf.func()`.
+
+`ctx.Tokens` is narrowed to exactly the audiences you declared, so an undeclared audience is a compile error rather than a runtime throw:
+
+```ts
+async (
+  ctx: RayfinContext<AppSchema, AudienceType.Sql | AudienceType.Storage>,
+) => {
+  const sqlToken: string = ctx.Tokens.Sql; // ok
+  const storageToken: string = ctx.Tokens.Storage; // ok
+  ctx.Tokens.Fabric; // compile error — not declared
+};
+```
+
+Values are typed `string`, not `string | undefined`.
+Declaring an audience registers its binding, but does not guarantee token availability or resource access.
+If the host does not supply a declared token, reading its `ctx.Tokens` property throws.
+
+### The schema argument
+
+`RayfinContext` takes your app schema first — the same one you pass to `RayfinClient<AppSchema>` — so the data client stays typed while you add audiences:
+
+```ts
+async (ctx: RayfinContext<AppSchema, AudienceType.Sql>) => {
+  const data = ctx.getDataClient(); // typed by AppSchema
+  const token = ctx.Tokens.Sql;
+};
+```
+
+If a function needs audiences but no data access, pass the default schema explicitly:
+
+```ts
+async (ctx: RayfinContext<Record<string, any>, AudienceType.Fabric>) => {
+  const token = ctx.Tokens.Fabric;
+};
+```
+
+## The third argument
+
+`udf.func()` still takes a third argument, and it stays `[]`. Audience-scoped connections are declared entirely in the context annotation — there is nothing to add there:
+
+```ts
+udf.func(
+  "syncWarehouse",
+  async (ctx: RayfinContext<AppSchema, AudienceType.Sql>): Promise<void> => {
+    const token = ctx.Tokens.Sql;
+  },
+  [],
+);
+```
+
+## Supported audiences
+
+`AudienceType` is the source of truth — inventing a member will not compile:
+
+`Sql`, `Storage`, `Fabric`, `AzureAI`, `ADO`.
+
+A Power BI semantic model is **not** reachable this way; use the `fabric-semanticmodel` connector instead.
+
+## How audiences reach the deployment
+
+Type arguments are erased before your function runs, so the audiences have to be recovered at build time. `npx rayfin up` resolves them with the TypeScript compiler and writes the resolved union into the deployment metadata, which is what the worker binds against.
+
+Because the compiler does the resolving, a type alias works:
+
+```ts
+type SqlAccess = AudienceType.Sql;
+
+// Resolves to AudienceType.Sql and binds a Sql connection.
+async (ctx: RayfinContext<AppSchema, SqlAccess>) => {
+  const token = ctx.Tokens.Sql;
+};
+```
+
+Writing audiences **literally** is still the clearer default, and there is one case where it is required: if the functions project has no `tsconfig.json`, the CLI has no compiler to ask and falls back to reading the annotation's syntax. An alias then resolves to its own name rather than the audience it stands for. The CLI warns when it is in that mode — treat the warning as a real problem, not noise.
+
+The context parameter must also carry an explicit `RayfinContext<...>` annotation. Typegen identifies the context parameter by that annotation; an unannotated parameter is treated as a request-body parameter instead.
+
+## Migrating from `ctx.getToken()`
+
+`ctx.getToken(audienceType)` is **deprecated**. It is flagged by `@typescript-eslint/no-deprecated`, which the scaffolded ESLint config reports as an error.
+
+```ts
+// Before
+udf.func(
+  "queryData",
+  async (ctx: RayfinContext): Promise<void> => {
+    const token = ctx.getToken(AudienceType.Sql);
+  },
+  [udf.connection({ audienceType: AudienceType.Sql })],
+);
+
+// After
+udf.func(
+  "queryData",
+  async (ctx: RayfinContext<AppSchema, AudienceType.Sql>): Promise<void> => {
+    const token = ctx.Tokens.Sql;
+  },
+  [],
 );
 ```
 
-- `udf.connection({ audienceType })` declares the delegated connection.
-- `ctx.getToken(audienceType)` returns the OBO access token as a `string`. It throws if no connection was declared for that audience.
-- The connection declaration is what makes the token available — declaring the audience and calling `getToken` with the same audience always go together.
+Move the audience from the third argument into the annotation, then replace the call with the property.
+
+**Both halves are required.** The array keeps working at *runtime* — array audiences are unioned with the annotated ones, so a deployed function still binds the connection. But it no longer carries any type information: `TokenTypes` defaults to `never`, so a handler left as `ctx: RayfinContext<AppSchema>` stops compiling at `ctx.getToken(AudienceType.Sql)` even with `Sql` declared in the array. Add the audience to the annotation first; the array alone is not enough.
 
 ## Wrapping the token for Azure SDK clients
 
@@ -51,12 +158,12 @@ class ContextTokenCredential implements TokenCredential {
 }
 ```
 
-Pass `new ContextTokenCredential(ctx.getToken(AudienceType.X))` wherever an Azure SDK client asks for a credential.
+Pass `new ContextTokenCredential(ctx.Tokens.X)` wherever an Azure SDK client asks for a credential.
 The per-resource guides below use this helper.
 
 ## Choose a recipe
 
-Find what you want to connect to. Each row links to a task-oriented walkthrough; the `AudienceType` is the value you pass to `udf.connection()` and `ctx.getToken()`. A single audience can back more than one use case (for example `Storage` covers both Fabric OneLake and Azure Blob).
+Find what you want to connect to. Each row links to a task-oriented walkthrough; the `AudienceType` is the value you put in the context annotation and the key you read off `ctx.Tokens`. A single audience can back more than one use case (for example `Storage` covers both Fabric OneLake and Azure Blob).
 
 | I want to connect to…                            | `AudienceType` | Recipe                                                               |
 | ------------------------------------------------ | -------------- | -------------------------------------------------------------------- |
@@ -64,26 +171,24 @@ Find what you want to connect to. Each row links to a task-oriented walkthrough;
 | Azure SQL Database                               | `Sql`          | [Add a Fabric resource](./add-fabric-resource.md#sql-databases)      |
 | Fabric OneLake files                             | `Storage`      | [Add a Fabric resource](./add-fabric-resource.md#onelake-files)      |
 | Azure Blob / Table / Queue                       | `Storage`      | [Add an Azure resource](./add-azure-resource.md#blob-storage)        |
-| Fabric Eventhouse (KQL)                          | `Kusto`        | [Add a Fabric resource](./add-fabric-resource.md#eventhouse-and-kql) |
-| Azure Data Explorer                              | `Kusto`        | [Add a Fabric resource](./add-fabric-resource.md#eventhouse-and-kql) |
 | Microsoft Fabric REST API                        | `Fabric`       | [Add a Fabric resource](./add-fabric-resource.md#fabric-rest-api)    |
-| Azure Key Vault                                  | `KeyVault`     | [Add an Azure resource](./add-azure-resource.md#key-vault)           |
-| Azure Cosmos DB                                  | `CosmosDB`     | [Add an Azure resource](./add-azure-resource.md#cosmos-db)           |
-| Azure Event Grid                                 | `EventGrid`    | [Add an Azure resource](./add-azure-resource.md#event-grid)          |
 | Azure AI Foundry                                 | `AzureAI`      | [Add Azure AI Foundry](./add-foundry.md)                             |
 | Azure DevOps                                     | `ADO`          | [Add Azure DevOps](./add-ado.md)                                     |
-| WorkIQ                                           | `WorkIQ`       | [Add WorkIQ](./add-work-iq.md)                                       |
 
-To look up a Fabric item's connection coordinates (SQL endpoint, OneLake path, Kusto query URI), see [Get Fabric info](./get-fabric-info.md).
+To look up a Fabric item's connection coordinates (SQL endpoint or OneLake path), see [Get Fabric info](./get-fabric-info.md).
 
 ## Rules
 
+- **Declare generic audiences in the annotation** and read them with `ctx.Tokens.<Audience>`. Prefer literal `AudienceType.X`, and keep a `tsconfig.json` in the functions project so the CLI can resolve anything that isn't.
+- **Pass `[]` as the third argument** to `udf.func()`.
 - **Use real endpoint URLs** — don't hardcode a guess or read them from `process.env`. For Fabric items, [Get Fabric info](./get-fabric-info.md) shows how to look them up.
-- Declare every connection in the third argument to `udf.func()`.
-- Use `ctx.getToken(AudienceType.X)` — never acquire tokens manually.
+- Never acquire tokens manually.
+- Grant resource access to the app identity, and keep its tokens server-side; never return them as function results.
 - Install resource SDK packages in `rayfin/functions/package.json`, not the project root.
 
 ## Local development
 
-When you run `npx rayfin dev functions apply`, the local host acquires delegated tokens interactively for debugging, so `ctx.getToken()` works against your declared audiences without a deployment.
+`npx rayfin dev` and `npx rayfin dev functions apply` start a local Azure Functions Core Tools host.
+External resource tokens use the identity and permissions of the account the builder signs in with in the local Functions host.
+Deployed Functions instead use the [application identity](../index.md#application-authentication).
 See [`npx rayfin dev functions apply`](../../cli/functions/dev-apply.md).

package/assets/docs/functions/index.md

@@ -29,6 +29,44 @@ npx rayfin functions init
 This creates `rayfin/functions/`, installs dependencies, and generates the initial `types.ts`.
 See [`npx rayfin functions init`](../cli/functions/init.md) for the full command reference.
 
+## Application authentication
+
+Enabled Functions require explicit application authentication in `rayfin/rayfin.yml`:
+
+```yaml
+services:
+  functions:
+    enabled: true
+    auth:
+      type: application
+    buildCommand: npm run build
+```
+
+New Functions scaffolds set `auth.type: application`.
+For an existing app, set it explicitly; loading the configuration does not add a default or migrate an older auth mode.
+Disabled Functions may omit `auth`, but any supplied `auth` must include `type: application`.
+No feature flag is needed.
+
+Full `npx rayfin up` and normal `npx rayfin dev` validate this setting before applying project settings to either the Fabric or Docker backend.
+Run a full `npx rayfin up` to apply the YAML auth mode to an existing remote app.
+Standalone `npx rayfin dev functions apply`, `npx rayfin up functions deploy`, and `npx rayfin up staticapp deploy` do not perform this project-settings validation or change the remote Functions auth mode.
+
+Deployed Functions use two separate authentication paths:
+
+| Access path | Credential | Identity and permissions |
+| --- | --- | --- |
+| External connections through `ctx.Tokens.*` | Platform-provided resource token | Application identity and its permissions on the external resource |
+| Rayfin DB through `ctx.getDataClient()` | The invocation's Rayfin token | The caller's identity and permissions on the Rayfin DB |
+
+For current Fabric apps, the app identity is the owner of the Fabric app item.
+External connections therefore use the item owner's permissions, not those of whichever app user invokes the function.
+Grant that identity the permissions required by each external resource and API your functions call.
+Declaring an audience or deploying Functions does not grant those permissions.
+App sign-in and authorization to invoke a function remain separate from the app identity's external resource access.
+Rayfin DB access always uses the Rayfin token and preserves the caller's identity and database permissions.
+Setting `services.functions.auth.type: application` does not switch Rayfin DB access to the application identity.
+See [Connecting to external resources](./connections/index.md) for audience declarations, permissions, and local development.
+
 ## Project structure
 
 After `npx rayfin functions init`, the functions project lives at `rayfin/functions/`:
@@ -86,6 +124,6 @@ See [`npx rayfin dev functions apply`](../cli/functions/dev-apply.md) for detail
 
 - [Writing functions](./writing-functions.md) — the `udf.func()` API, `RayfinContext`, and data access.
 - [Type generation](./typegen.md) — how `types.ts` is generated and kept in sync.
-- [Connecting to external resources](./connections/index.md) — delegated access to SQL, Storage, Key Vault, and more.
+- [Connecting to external resources](./connections/index.md) — app-identity access to SQL, Storage, the Fabric REST API, and more.
 - [Secrets](./secrets.md) — reading secrets from inside a function.
 - [Invoking functions from the frontend](./invoking-from-frontend.md) — calling functions with `RayfinClient`.

package/assets/docs/functions/secrets.md

@@ -4,7 +4,7 @@ sidebar_position: 3
 
 # Secrets
 
-Functions read secret values through `ctx.getSecret(name)` on [`RayfinContext`](./writing-functions.md#rayfincontext-api).
+Functions read secret values as typed properties on `ctx.Secrets`, part of [`RayfinContext`](./writing-functions.md#rayfincontext-api).
 
 ```ts
 import {
@@ -16,23 +16,34 @@ const udf = new UserDataFunctions();
 
 udf.func(
   "readApiKey",
-  async (ctx: RayfinContext): Promise<string> => {
-    const apiKey = ctx.getSecret("THIRD_PARTY_API_KEY");
-    if (!apiKey) {
-      throw new Error("Missing THIRD_PARTY_API_KEY secret.");
-    }
-    return apiKey;
+  async (ctx: RayfinContext<AppSchema>): Promise<string> => {
+    return ctx.Secrets.THIRD_PARTY_API_KEY;
   },
   [],
 );
 ```
 
+There is nothing to add to the function's declaration and nothing to add to your data schema — declaring the secret with the CLI is what types it.
+
+## How the names are typed
+
+`npx rayfin secret set <NAME>` records the name in `rayfin.yml`, and the CLI regenerates `rayfin/functions/src/secrets.generated.ts`. That file augments the SDK's `RayfinSecretRegistry` interface, which is what narrows `ctx.Secrets`:
+
+```ts
+ctx.Secrets.THIRD_PARTY_API_KEY; // string
+ctx.Secrets.NOT_DECLARED; // compile error
+```
+
+- Values are typed `string`, not `string | undefined` — the name was declared, so the value is modelled as present. Reading a declared secret that was not supplied throws a diagnosable error rather than silently yielding `undefined`.
+- Nothing imports `secrets.generated.ts`; it only has to be part of the compilation. **Never hand-edit it** — the CLI overwrites it, and the typegen watcher deliberately ignores it so regenerating doesn't loop.
+- Deleting a secret narrows the type, so stale references stop compiling instead of failing at invocation.
+
 ## How resolution works
 
-`ctx.getSecret(name)` returns `string | undefined`. It resolves in this order:
+`ctx.Secrets.<NAME>` resolves in this order:
 
 1. The host-provided secret bag delivered with the invocation.
-2. `process.env[name]` as a fallback.
+2. `process.env[NAME]` as a fallback.
 
 ## Setting secrets
 
@@ -48,7 +59,7 @@ See [Managing secrets](../cli/secrets.md) for the full `npx rayfin secret` comma
 ## Secrets in local development
 
 The host-provided secret bag is only present for deployed invocations.
-When you debug locally with `npx rayfin dev functions apply`, add the same key under `Values` in `rayfin/functions/local.settings.json` so it flows into `process.env` and is picked up by the `getSecret` fallback:
+When you debug locally with `npx rayfin dev functions apply`, add the same key under `Values` in `rayfin/functions/local.settings.json` so it flows into `process.env` and is picked up by the fallback:
 
 ```jsonc
 {
@@ -64,7 +75,24 @@ When you debug locally with `npx rayfin dev functions apply`, add the same key u
 `local.settings.json` is git-ignored, so these values stay on your machine.
 See [Secrets in local development](../cli/secrets.md#using-secrets-in-local-development) for more.
 
+## The deprecated `ctx.getSecret()`
+
+`ctx.getSecret(name)` returns `string | undefined` and is **deprecated** — it is flagged by `@typescript-eslint/no-deprecated`, which the scaffolded ESLint config reports as an error.
+
+```ts
+// Before
+const apiKey = ctx.getSecret("THIRD_PARTY_API_KEY");
+if (!apiKey) {
+  throw new Error("Missing THIRD_PARTY_API_KEY secret.");
+}
+
+// After
+const apiKey = ctx.Secrets.THIRD_PARTY_API_KEY;
+```
+
+It remains valid for a value deliberately **not** modelled in `rayfin.yml` — a host-injected environment variable, for example. Suppress the lint at that one call site rather than project-wide.
+
 ## Best practices
 
-- Prefer secrets set with `npx rayfin secret set <NAME>` as the source of truth for deployed functions.
+- Declare every secret with `npx rayfin secret set <NAME>` and read it from `ctx.Secrets` — never hard-code a secret name string.
 - Use the `process.env` fallback only for local debugging — do not make it your primary production secret source.