feat(blueprint): add Okta runtime identity reference

docs/reference/architecture.mdx

@@ -241,6 +241,57 @@ flowchart LR
 4. Apply. The runner executes the plan by calling `openshell` CLI commands.
 5. Status. The runner reports current state.
 
+### Experimental Runtime Identity
+
+The direct blueprint runner can opt in to an Okta runtime-identity component.
+This experimental reference capability is not enabled by the shipped blueprint, and normal `$$nemoclaw onboard` does not collect or provision its inputs.
+It is for operators extending a reviewed blueprint with a tenant-specific Okta profile.
+
+Enable provider-derived policy on the target gateway before applying a blueprint that attaches this component:
+
+```bash
+openshell settings set --global --key providers_v2_enabled --value true --yes
+```
+
+Copy `nemoclaw-blueprint/provider-profiles/okta-runtime-v1.yaml` into the blueprint you operate.
+Set its `token_url` to the tenant's authorization-server token endpoint, replace `api.example.okta.com` with the approved upstream API host, and add only the API scopes that the Okta authorization server grants to `refresh.scopes`.
+Keep the token endpoint and upstream host in the profile so refresh material and bearer-token presentation cannot be redirected by blueprint input.
+
+Configure the reference under `components`:
+
+```yaml
+identity:
+  okta:
+    profile_path: provider-profiles/acme-okta-runtime.yaml
+    provider_type: okta-runtime-v1
+    provider_name: acme-okta-runtime
+    credential_key: OKTA_ACCESS_TOKEN
+    client_id_env: OKTA_CLIENT_ID
+    refresh_token_env: OKTA_REFRESH_TOKEN
+    client_secret_env: OKTA_CLIENT_SECRET
+```
+
+`client_secret_env` is optional, but when it is configured its environment variable must be present.
+Before applying the blueprint, export the named environment variables in the host process that runs the direct blueprint runner.
+Obtain the refresh token through an authorized OAuth bootstrap flow for the same Okta client and authorization server as the profile.
+`openshell gateway login` authenticates a CLI user to the gateway and is not part of this runtime-credential flow.
+
+During apply, the runner imports the profile, creates a runtime-credential provider, configures gateway-managed OAuth refresh, rotates an initial access token, and attaches the provider to the sandbox.
+The refresh token and optional client secret are passed as secret material and stay in the gateway credential store.
+The sandbox receives an opaque `OKTA_ACCESS_TOKEN` placeholder, and the OpenShell L7 proxy substitutes the current access token only for admitted HTTPS requests.
+
+Check the gateway-side state without printing credential values:
+
+```bash
+openshell provider refresh status acme-okta-runtime --credential-key OKTA_ACCESS_TOKEN
+openshell sandbox provider list <sandbox-name>
+```
+
+The same blueprint can optionally configure `components.policy.middlewares`.
+Those entries use the OpenShell middleware API to extend the existing middleware chain with endpoint selection, ordering, and `fail_closed` behavior.
+Middleware is optional for Okta access-token refresh and presentation.
+Use it only when the deployment has a compatible middleware installed for additional controls, such as identity assertions or on-behalf-of exchange.
+
 ## Sandbox Environment
 
 <AgentOnly variant="openclaw,hermes">

nemoclaw-blueprint/provider-profiles/okta-runtime-v1.yaml

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Template profile for the experimental blueprint identity wrapper. Copy this
+# file, replace the example authorization-server URL and API host, and add
+# only tenant-approved API scopes under `refresh.scopes` before use.
+id: okta-runtime-v1
+display_name: Okta Runtime Credentials v1
+description: Gateway-managed Okta access-token refresh for an attached sandbox
+category: agent
+credentials:
+  - name: OKTA_ACCESS_TOKEN
+    description: Short-lived Okta API access token
+    env_vars:
+      - OKTA_ACCESS_TOKEN
+    required: true
+    auth_style: bearer
+    header_name: authorization
+    refresh:
+      strategy: oauth2_refresh_token
+      token_url: https://example.okta.com/oauth2/default/v1/token
+      refresh_before_seconds: 300
+      max_lifetime_seconds: 3600
+      material:
+        - name: client_id
+          required: true
+        - name: refresh_token
+          required: true
+          secret: true
+        - name: client_secret
+          required: false
+          secret: true
+endpoints:
+  - host: api.example.okta.com
+    port: 443
+    protocol: rest
+    enforcement: enforce
+    rules:
+      - allow: { method: GET, path: "/**" }
+binaries:
+  - /usr/local/bin/node
+  - /usr/bin/node
+  - /usr/local/bin/curl
+  - /usr/bin/curl
+inference_capable: false

nemoclaw/src/blueprint/runner-identity.test.ts

@@ -0,0 +1,222 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type fs from "node:fs";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import YAML from "yaml";
+
+interface FsEntry {
+  type: "file" | "dir";
+  content?: string;
+}
+
+const store = new Map<string, FsEntry>();
+const mockExeca = vi.fn();
+
+vi.mock("node:os", () => ({ homedir: () => "/fakehome" }));
+vi.mock("node:crypto", () => ({ randomUUID: () => "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }));
+vi.mock("node:fs", async (importOriginal) => {
+  const original = await importOriginal<typeof fs>();
+  return {
+    ...original,
+    mkdirSync: vi.fn((path: string) => store.set(path, { type: "dir" })),
+    readFileSync: (path: string) => {
+      const entry = store.get(path);
+      if (entry?.type !== "file") throw new Error(`ENOENT: ${path}`);
+      return entry.content ?? "";
+    },
+    writeFileSync: vi.fn((path: string, content: string) =>
+      store.set(path, { type: "file", content }),
+    ),
+    readdirSync: (path: string) => {
+      const prefix = path.endsWith("/") ? path : `${path}/`;
+      const entries = [...store.keys()]
+        .filter((key) => key.startsWith(prefix))
+        .map((key) => key.slice(prefix.length).split("/")[0]);
+      if (entries.length === 0 && !store.has(path)) throw new Error(`ENOENT: ${path}`);
+      return [...new Set(entries)];
+    },
+  };
+});
+vi.mock("execa", () => ({ execa: (...args: unknown[]) => mockExeca(...args) }));
+vi.mock("./ssrf.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./ssrf.js")>();
+  return {
+    ...actual,
+    validateEndpointUrl: vi.fn(async (url: string) => ({
+      url,
+      pinnedUrl: url,
+      protocol: "https:",
+      hostname: new URL(url).hostname,
+      dnsResolved: false,
+    })),
+  };
+});
+
+const { actionApply, loadBlueprint } = await import("./runner.js");
+
+function blueprint(overrides: Record<string, unknown> = {}): Parameters<typeof actionApply>[1] {
+  return {
+    components: {
+      inference: {
+        profiles: {
+          default: {
+            provider_type: "openai",
+            provider_name: "test-provider",
+            endpoint: "https://api.example.com/v1",
+            model: "test-model",
+          },
+        },
+      },
+      sandbox: { image: "openclaw", name: "test-sandbox", forward_ports: [18789] },
+      ...overrides,
+    },
+  };
+}
+
+function oktaIdentity(profilePath = "provider-profiles/okta-runtime-v1.yaml") {
+  return {
+    profile_path: profilePath,
+    provider_type: "okta-runtime-v1",
+    provider_name: "acme-okta-runtime",
+    credential_key: "OKTA_ACCESS_TOKEN",
+    client_id_env: "OKTA_CLIENT_ID",
+    refresh_token_env: "OKTA_REFRESH_TOKEN",
+    client_secret_env: "OKTA_CLIENT_SECRET",
+  };
+}
+
+describe("blueprint identity wrapper", () => {
+  beforeEach(() => {
+    store.clear();
+    vi.clearAllMocks();
+    mockExeca.mockResolvedValue({ exitCode: 0, stdout: "", stderr: "" });
+    delete process.env.NEMOCLAW_BLUEPRINT_PATH;
+  });
+
+  afterEach(() => {
+    delete process.env.OKTA_CLIENT_ID;
+    delete process.env.OKTA_REFRESH_TOKEN;
+    delete process.env.OKTA_CLIENT_SECRET;
+    vi.restoreAllMocks();
+  });
+
+  it("accepts an opt-in Okta identity and fail-closed middleware configuration", () => {
+    const input = blueprint({
+      identity: { okta: oktaIdentity() },
+      policy: {
+        middlewares: {
+          identity_guard: {
+            middleware: "acme/identity-guard",
+            order: 10,
+            on_error: "fail_closed",
+            endpoints: { include: ["api.example.okta.com"] },
+          },
+        },
+      },
+    });
+    store.set("blueprint.yaml", { type: "file", content: YAML.stringify(input) });
+
+    expect(loadBlueprint()).toEqual(input);
+  });
+
+  it("rejects profile paths that escape the blueprint directory", async () => {
+    await expect(
+      actionApply("default", blueprint({ identity: { okta: oktaIdentity("../outside.yaml") } })),
+    ).rejects.toThrow(/profile_path must stay inside/i);
+  });
+
+  it("configures refresh from scoped environment material and attaches the runtime provider", async () => {
+    process.env.OKTA_CLIENT_ID = "client-id";
+    process.env.OKTA_REFRESH_TOKEN = "refresh-secret";
+    process.env.OKTA_CLIENT_SECRET = "client-secret";
+
+    await actionApply("default", blueprint({ identity: { okta: oktaIdentity() } }));
+
+    expect(mockExeca).toHaveBeenCalledWith(
+      "openshell",
+      ["provider", "profile", "import", "--file", "provider-profiles/okta-runtime-v1.yaml"],
+      expect.objectContaining({ reject: false }),
+    );
+    expect(mockExeca).toHaveBeenCalledWith(
+      "openshell",
+      [
+        "provider",
+        "create",
+        "--name",
+        "acme-okta-runtime",
+        "--type",
+        "okta-runtime-v1",
+        "--runtime-credentials",
+      ],
+      expect.objectContaining({ reject: false }),
+    );
+    const refreshCall = mockExeca.mock.calls.find(
+      (call) => Array.isArray(call[1]) && call[1][0] === "provider" && call[1][2] === "configure",
+    );
+    if (!refreshCall) throw new Error("Okta refresh configure call not found");
+    expect(refreshCall[1]).toContain("client_id=client-id");
+    expect(refreshCall[1]).not.toContain("refresh-secret");
+    expect(refreshCall[1]).not.toContain("client-secret");
+    expect(refreshCall[2].env.OKTA_REFRESH_TOKEN).toBe("refresh-secret");
+    expect(refreshCall[2].env.OKTA_CLIENT_SECRET).toBe("client-secret");
+    expect(mockExeca).toHaveBeenCalledWith(
+      "openshell",
+      ["sandbox", "provider", "attach", "test-sandbox", "acme-okta-runtime"],
+      expect.objectContaining({ reject: false }),
+    );
+  });
+
+  it("composes fail-closed middleware while retaining existing middleware", async () => {
+    mockExeca.mockImplementation(async (_command: string, args: string[]) => {
+      if (args[0] === "policy" && args[1] === "get") {
+        return {
+          exitCode: 0,
+          stdout: [
+            "Version: 1",
+            "Hash: sha256:test",
+            "---",
+            "version: 1",
+            "network_policies: {}",
+            "network_middlewares:",
+            "  existing:",
+            "    middleware: openshell/regex",
+            "    endpoints:",
+            "      include: [api.example.com]",
+            "",
+          ].join("\n"),
+          stderr: "",
+        };
+      }
+      return { exitCode: 0, stdout: "", stderr: "" };
+    });
+    await actionApply(
+      "default",
+      blueprint({
+        policy: {
+          middlewares: {
+            identity_guard: {
+              middleware: "acme/identity-guard",
+              order: 10,
+              on_error: "fail_closed",
+              endpoints: { include: ["api.example.okta.com"] },
+            },
+          },
+        },
+      }),
+    );
+
+    const merged = [...store.entries()].find(([path]) => path.endsWith("/merged-policy.yaml"))?.[1]
+      .content;
+    if (!merged) throw new Error("merged policy file not written");
+    expect(YAML.parse(merged).network_middlewares).toMatchObject({
+      existing: { middleware: "openshell/regex" },
+      identity_guard: {
+        middleware: "acme/identity-guard",
+        order: 10,
+        on_error: "fail_closed",
+      },
+    });
+  });
+});