@ory/argus 0.13.8 → 0.14.0

package/dist/auth.js

@@ -12,6 +12,39 @@
  * package via dynamic import so the CJS-emitted core stays compatible
  * with its ESM-only export shape.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_LOGIN_TIMEOUT_MS = exports.LOOPBACK_PORTS = void 0;
 exports.detectHeadless = detectHeadless;
@@ -20,9 +53,12 @@ exports.generateCodeVerifier = generateCodeVerifier;
 exports.sha256Base64Url = sha256Base64Url;
 exports.buildAuthorizeUrl = buildAuthorizeUrl;
 exports.refreshAccessToken = refreshAccessToken;
+exports.displayNameFromIdToken = displayNameFromIdToken;
 const node_crypto_1 = require("node:crypto");
 const node_http_1 = require("node:http");
 const node_url_1 = require("node:url");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 /** Loopback ports tried in order. All must be registered as redirect URIs on the Ory OAuth2 client. */
 exports.LOOPBACK_PORTS = [47823, 47824, 47825, 47826];
 /** Hard timeout if the user never returns to the browser. */
@@ -201,6 +237,10 @@ function waitForCallback(server, opts) {
                 return;
             }
             const url = new node_url_1.URL(req.url ?? "/", `http://127.0.0.1`);
+            if (url.pathname === "/favicon.ico") {
+                respondFavicon(res);
+                return;
+            }
             if (url.pathname !== "/callback") {
                 respond(res, 404, "Not Found");
                 return;
@@ -238,18 +278,41 @@ function respondHtml(res, status, html) {
     res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
     res.end(html);
 }
+/**
+ * Serve the shared Ory favicon (identical to console.ory.com's) so the sign-in
+ * result page carries the same tab icon as the Console. It ships alongside the
+ * built dashboard at `dist/webapp/favicon.ico`; if that file isn't present
+ * (e.g. the webapp wasn't built), fall back to a 404 — the page still renders,
+ * just without a favicon. Same-origin on the loopback server, so no external
+ * request is made.
+ */
+function respondFavicon(res) {
+    // Compiled to dist/auth.js; the SPA (and its favicon) is built to dist/webapp.
+    const file = path.join(__dirname, "webapp", "favicon.ico");
+    try {
+        const buf = fs.readFileSync(file);
+        res.writeHead(200, {
+            "content-type": "image/x-icon",
+            "cache-control": "no-store",
+        });
+        res.end(buf);
+    }
+    catch {
+        respond(res, 404, "Not Found");
+    }
+}
 /**
  * The page the browser lands on after the OAuth2 redirect. The whole point is
  * to make the next action unambiguous: on success it tells the user, in plain
  * words, that they can close the tab and return to the terminal (the #1
- * source of "is it done? do I close this?" confusion). Self-contained HTML —
- * inline styles only, Ory-branded (Indigo #4F46E5), no external requests — so
- * it renders identically offline and on the loopback origin.
+ * source of "is it done? do I close this?" confusion). Inline styles only, no
+ * external requests — the only asset is the same-origin Ory favicon the
+ * loopback server serves — so it renders identically offline.
  */
 function resultPage(kind) {
     const view = {
         success: {
-            accent: "#4F46E5", // Ory Indigo
+            accent: "#22C55E", // green — a positive "done" check
             icon: "&#10003;", // ✓
             title: "Signed in to Ory",
             body: "You can <strong>close this tab</strong> and return to your terminal — setup continues automatically.",
@@ -272,6 +335,7 @@ function resultPage(kind) {
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" href="/favicon.ico">
 <title>${view.title}</title>
 <style>
   :root { color-scheme: light dark; }
@@ -381,6 +445,10 @@ function tokensFromTokenResponse(json, clientId, fallbackRefreshToken) {
 }
 /** Best-effort sub-claim extraction from a JWT id_token. Returns undefined on any failure. */
 function subjectFromIdToken(idToken) {
+    return claimsFromIdToken(idToken)?.sub;
+}
+/** Best-effort JWT id_token payload decode. Returns undefined on any failure. */
+function claimsFromIdToken(idToken) {
     if (!idToken)
         return undefined;
     const parts = idToken.split(".");
@@ -388,9 +456,26 @@ function subjectFromIdToken(idToken) {
         return undefined;
     try {
         const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
-        return typeof payload.sub === "string" ? payload.sub : undefined;
+        return payload && typeof payload === "object" ? payload : undefined;
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Best-effort human-readable name for the signed-in user, pulled from the
+ * id_token's identity claims — `email`, then `name`, then `preferred_username`.
+ * Returns undefined when the token carries none of them (e.g. an `openid`-only
+ * token), so callers fall back to the opaque subject id.
+ */
+function displayNameFromIdToken(idToken) {
+    const claims = claimsFromIdToken(idToken);
+    if (!claims)
+        return undefined;
+    for (const key of ["email", "name", "preferred_username"]) {
+        const v = claims[key];
+        if (typeof v === "string" && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}

package/dist/branding.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The umbrella brand and the names for every resource the installer creates in
+ * (or for) an Ory project. Centralized here so every install path — the web
+ * wizard, the TTY wizard, and the agent-identity gates — produces the same,
+ * self-describing names, and so the naming policy lives in one place.
+ *
+ * The policy has two tiers, because many users install these plugins against
+ * the **same** Ory project:
+ *
+ *  - **Shared** resources (one per project, reused by every user/harness) get a
+ *    **stable, identity-free** name so all installs find and reuse the one
+ *    resource instead of duplicating it: {@link USER_LOGIN_CLIENT_NAME} and the
+ *    permission namespace ({@link PERMISSION_NAMESPACE}).
+ *  - **Per-installer** resources (many per project by design — confidential
+ *    per-machine DCR credentials, write-once API keys) get an **attributable**
+ *    name carrying *who* and *where*, so a shared project's resource list stays
+ *    legible and prunable: {@link agentClientName}, {@link projectApiKeyName}.
+ *
+ * Everything shares the {@link PRODUCT_NAME} prefix so the plugin's resources
+ * group together and are instantly recognizable in a shared Ory Console.
+ */
+/** Human-readable umbrella name for everything this product creates. */
+export declare const PRODUCT_NAME = "Ory Agent Security";
+/**
+ * The public PKCE client the human's browser sign-in uses. It is a *public*
+ * client (no secret), so every user on a project shares the one client — the
+ * installer dedupes by this exact name. Stable and identity-free on purpose.
+ */
+export declare const USER_LOGIN_CLIENT_NAME = "Ory Agent Security \u00B7 user login (PKCE)";
+/**
+ * Names an older installer may have given the shared user-login client. The
+ * reuse probe matches these too, so renaming the client never orphans one
+ * created by a previous install (which would then mint a duplicate).
+ */
+export declare const LEGACY_USER_LOGIN_CLIENT_NAMES: string[];
+/** All names the shared user-login client may carry, newest first. */
+export declare const USER_LOGIN_CLIENT_NAMES: string[];
+/** Default name for a project the installer creates. Harness-agnostic, since a
+ *  team typically points several harnesses at one shared project. */
+export declare const DEFAULT_PROJECT_NAME = "Ory Agent Security";
+/** The shared permission-model namespace (an OPL class name, so it must stay a
+ *  bare identifier — no spaces/branding — and stable across installs). */
+export declare const PERMISSION_NAMESPACE = "AgentTools";
+/**
+ * The client_name for an agent's (or sub-agent's) OAuth2 identity registered
+ * via DCR. These are confidential, per-machine credentials — many per shared
+ * project by design — so the name is attributable: the harness it belongs to
+ * and the host it was registered from (plus the sub-agent type, when it is one).
+ */
+export declare function agentClientName(opts: {
+    harness?: string;
+    host: string;
+    subAgentType?: string;
+}): string;
+/**
+ * The name for a project API key minted for runtime permission checks. Ory only
+ * returns a key's secret at creation, so a key can't be reused across machines
+ * — each installer that mints one gets its own. The name therefore carries the
+ * signed-in *user* (the axis that matters on a shared project) plus the host, so
+ * a team admin can tell whose key is whose and prune stale ones. No timestamp:
+ * the Ory Console's key listing already shows a "Date Added" column. `user`
+ * falls back to the host alone when it isn't resolvable (e.g. login skipped).
+ */
+export declare function projectApiKeyName(opts: {
+    host: string;
+    user?: string;
+}): string;

package/dist/branding.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * The umbrella brand and the names for every resource the installer creates in
+ * (or for) an Ory project. Centralized here so every install path — the web
+ * wizard, the TTY wizard, and the agent-identity gates — produces the same,
+ * self-describing names, and so the naming policy lives in one place.
+ *
+ * The policy has two tiers, because many users install these plugins against
+ * the **same** Ory project:
+ *
+ *  - **Shared** resources (one per project, reused by every user/harness) get a
+ *    **stable, identity-free** name so all installs find and reuse the one
+ *    resource instead of duplicating it: {@link USER_LOGIN_CLIENT_NAME} and the
+ *    permission namespace ({@link PERMISSION_NAMESPACE}).
+ *  - **Per-installer** resources (many per project by design — confidential
+ *    per-machine DCR credentials, write-once API keys) get an **attributable**
+ *    name carrying *who* and *where*, so a shared project's resource list stays
+ *    legible and prunable: {@link agentClientName}, {@link projectApiKeyName}.
+ *
+ * Everything shares the {@link PRODUCT_NAME} prefix so the plugin's resources
+ * group together and are instantly recognizable in a shared Ory Console.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISSION_NAMESPACE = exports.DEFAULT_PROJECT_NAME = exports.USER_LOGIN_CLIENT_NAMES = exports.LEGACY_USER_LOGIN_CLIENT_NAMES = exports.USER_LOGIN_CLIENT_NAME = exports.PRODUCT_NAME = void 0;
+exports.agentClientName = agentClientName;
+exports.projectApiKeyName = projectApiKeyName;
+/** Human-readable umbrella name for everything this product creates. */
+exports.PRODUCT_NAME = "Ory Agent Security";
+/**
+ * The public PKCE client the human's browser sign-in uses. It is a *public*
+ * client (no secret), so every user on a project shares the one client — the
+ * installer dedupes by this exact name. Stable and identity-free on purpose.
+ */
+exports.USER_LOGIN_CLIENT_NAME = `${exports.PRODUCT_NAME} · user login (PKCE)`;
+/**
+ * Names an older installer may have given the shared user-login client. The
+ * reuse probe matches these too, so renaming the client never orphans one
+ * created by a previous install (which would then mint a duplicate).
+ */
+exports.LEGACY_USER_LOGIN_CLIENT_NAMES = ["ory-agent-plugin"];
+/** All names the shared user-login client may carry, newest first. */
+exports.USER_LOGIN_CLIENT_NAMES = [
+    exports.USER_LOGIN_CLIENT_NAME,
+    ...exports.LEGACY_USER_LOGIN_CLIENT_NAMES,
+];
+/** Default name for a project the installer creates. Harness-agnostic, since a
+ *  team typically points several harnesses at one shared project. */
+exports.DEFAULT_PROJECT_NAME = exports.PRODUCT_NAME;
+/** The shared permission-model namespace (an OPL class name, so it must stay a
+ *  bare identifier — no spaces/branding — and stable across installs). */
+exports.PERMISSION_NAMESPACE = "AgentTools";
+/**
+ * The client_name for an agent's (or sub-agent's) OAuth2 identity registered
+ * via DCR. These are confidential, per-machine credentials — many per shared
+ * project by design — so the name is attributable: the harness it belongs to
+ * and the host it was registered from (plus the sub-agent type, when it is one).
+ */
+function agentClientName(opts) {
+    const { harness, host, subAgentType } = opts;
+    if (subAgentType) {
+        const scope = harness ? `${harness}/${subAgentType}` : subAgentType;
+        return `${exports.PRODUCT_NAME} · sub-agent · ${scope} @ ${host}`;
+    }
+    return harness
+        ? `${exports.PRODUCT_NAME} · agent · ${harness} @ ${host}`
+        : `${exports.PRODUCT_NAME} · agent @ ${host}`;
+}
+/**
+ * The name for a project API key minted for runtime permission checks. Ory only
+ * returns a key's secret at creation, so a key can't be reused across machines
+ * — each installer that mints one gets its own. The name therefore carries the
+ * signed-in *user* (the axis that matters on a shared project) plus the host, so
+ * a team admin can tell whose key is whose and prune stale ones. No timestamp:
+ * the Ory Console's key listing already shows a "Date Added" column. `user`
+ * falls back to the host alone when it isn't resolvable (e.g. login skipped).
+ */
+function projectApiKeyName(opts) {
+    const who = opts.user && opts.user !== "agent:unknown" ? opts.user : null;
+    const where = who ? `${who} @ ${opts.host}` : opts.host;
+    return `${exports.PRODUCT_NAME}: Permission Checks - ${where}`;
+}

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "repo": "ory-agent-plugins",
-  "commit": "ff55031f181ceec7e06f8d7f3a6b2555c130a091",
-  "commitShort": "ff55031",
+  "commit": "7568c163e59fba25d64ede49c092fcca108a43f2",
+  "commitShort": "7568c16",
   "branch": "main",
-  "commitDate": "2026-07-15T13:59:17-07:00",
+  "commitDate": "2026-07-23T10:17:45-07:00",
   "dirty": false,
-  "builtAt": "2026-07-15T21:03:15.277Z"
+  "builtAt": "2026-07-23T17:21:55.389Z"
 }

package/dist/cli.d.ts

@@ -8,9 +8,9 @@
  * When `--project-url` is provided, requires the OAuth2 client id to be
  * resolvable from one of: the `--oauth2-client-id` flag, the
  * `ORY_OAUTH2_CLIENT_ID` env var, or an already-persisted value in the
- * shared config. The PKCE browser flow that runs when
- * `ORY_USER_LOGIN=true` can't self-register that client — surfacing the
- * requirement here keeps users from a silently-broken setup later.
+ * shared config. The PKCE browser flow (the user login runs every session)
+ * can't self-register that client — surfacing the requirement here keeps
+ * users from a silently-broken setup later.
  */
 export declare function runConfigureCommand(binName: string, args: string[]): void;
 /**

package/dist/cli.js

@@ -62,9 +62,9 @@ const client_js_1 = require("./client.js");
  * When `--project-url` is provided, requires the OAuth2 client id to be
  * resolvable from one of: the `--oauth2-client-id` flag, the
  * `ORY_OAUTH2_CLIENT_ID` env var, or an already-persisted value in the
- * shared config. The PKCE browser flow that runs when
- * `ORY_USER_LOGIN=true` can't self-register that client — surfacing the
- * requirement here keeps users from a silently-broken setup later.
+ * shared config. The PKCE browser flow (the user login runs every session)
+ * can't self-register that client — surfacing the requirement here keeps
+ * users from a silently-broken setup later.
  */
 function runConfigureCommand(binName, args) {
     let projectUrl;
@@ -72,9 +72,6 @@ function runConfigureCommand(binName, args) {
     let apiKey;
     let oauth2ClientId;
     let auditOnly = false;
-    // `undefined` = not specified (leave the persisted value alone);
-    // true/false = explicit enable/disable of the interactive user login.
-    let userLogin;
     // `undefined` = not specified; a string sets it; empty string ("") clears it
     // (via --no-user-subject-namespace) to fall back to direct SubjectID.
     let userSubjectNamespace;
@@ -98,12 +95,6 @@ function runConfigureCommand(binName, args) {
             case "--audit-only":
                 auditOnly = true;
                 break;
-            case "--user-login":
-                userLogin = true;
-                break;
-            case "--no-user-login":
-                userLogin = false;
-                break;
             case "--user-subject-namespace":
                 userSubjectNamespace = args[++i];
                 break;
@@ -117,28 +108,23 @@ function runConfigureCommand(binName, args) {
         !apiKey &&
         !oauth2ClientId &&
         !auditOnly &&
-        userLogin === undefined &&
         userSubjectNamespace === undefined) {
         const resolved = (0, config_js_1.resolveConfig)();
         const configPath = (0, config_js_1.getConfigPath)();
         console.log("Ory Plugin Configuration");
         console.log("========================");
         console.log("");
-        console.log(`Config file:      ${configPath}`);
+        console.log(`Config file:      ${configPath}${fs.existsSync(configPath) ? "" : " (not created yet)"}`);
         console.log(`Project URL:      ${resolved.projectUrl ?? "(not set)"} [${resolved.projectUrlSource}]`);
         console.log(`Project ID:       ${resolved.projectId ?? "(not set)"} [${resolved.projectIdSource}]`);
         console.log(`API Key:          ${resolved.apiKey ? "(set)" : "(not set)"} [${resolved.apiKeySource}]`);
         console.log(`OAuth2 Client ID: ${resolved.oauth2ClientId ?? "(not set)"} [${resolved.oauth2ClientIdSource}]`);
         console.log(`Audit Only:       ${resolved.auditOnly ? "yes" : "no"}`);
-        console.log(`User Login:       ${resolved.userLogin ? "on" : "off"} [${resolved.userLoginSource}]`);
         console.log(`User subject ns:  ${resolved.userSubjectNamespace ?? "(direct subject id)"} [${resolved.userSubjectNamespaceSource}]`);
         console.log("");
         console.log("To configure:");
         console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         console.log("");
-        console.log("To enable the interactive user login (PKCE browser flow at session start):");
-        console.log(`  npx ${binName} configure --user-login    (disable with --no-user-login)`);
-        console.log("");
         console.log("To address the user as a SubjectSet in permission checks (must match your tuples):");
         console.log(`  ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --user-subject-namespace User   (clear with --no-user-subject-namespace)`);
         console.log("");
@@ -151,20 +137,14 @@ function runConfigureCommand(binName, args) {
         console.log("  # ORY_PROJECT_ID=<project uuid> is stored for admin operations (not an SDK URL).");
         console.log("  export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
         console.log("  export ORY_AGENT_API_KEY=ory_pat_...");
-        console.log("  export ORY_USER_LOGIN=true");
         return;
     }
     if (auditOnly) {
-        // Audit-only mode: set the kill switch. Persist an explicit user-login
-        // choice too if one was passed, so it takes effect once audit-only is
-        // later turned off; audit-only itself disables login regardless.
-        (0, config_js_1.saveConfig)({ auditOnly: true, ...(userLogin !== undefined ? { userLogin } : {}) });
+        // Audit-only mode: set the kill switch (disables auth and checks entirely).
+        (0, config_js_1.saveConfig)({ auditOnly: true });
         const configPath = (0, config_js_1.getConfigPath)();
         console.log(`Configuration saved to ${configPath}`);
         console.log("  Mode: audit-only (logging enabled, auth and permission checks disabled)");
-        if (userLogin !== undefined) {
-            console.log(`  User login: ${userLogin ? "on" : "off"} (takes effect when audit-only is disabled)`);
-        }
         console.log("");
         console.log("This configuration is shared across all Ory agent plugins.");
         return;
@@ -207,34 +187,19 @@ function runConfigureCommand(binName, args) {
             process.exit(1);
         }
     }
-    // Enabling user login needs a project URL and a public OAuth2 client id
-    // to complete the PKCE flow. Warn (don't block) if either is missing —
-    // the operator may supply them separately or via env before running.
-    if (userLogin === true) {
-        // resolveConfig() already folds in the ORY_SDK_URL alias and the config
-        // file; OR in the URL being set on this same invocation.
-        const nextProjectUrl = projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
-        const nextClientId = oauth2ClientId ?? process.env.ORY_OAUTH2_CLIENT_ID ?? (0, config_js_1.loadConfig)().oauth2ClientId;
-        if (!nextProjectUrl || !nextClientId) {
-            const missing = [
-                !nextProjectUrl ? "a project URL (--project-url / --sdk-url / ORY_PROJECT_URL)" : null,
-                !nextClientId ? "an OAuth2 client id (--oauth2-client-id / ORY_OAUTH2_CLIENT_ID)" : null,
-            ].filter(Boolean);
-            console.warn(`Warning: user login is enabled but still missing ${missing.join(" and ")}.\n` +
-                "The PKCE browser flow can't complete until both are configured.");
-        }
-    }
     const update = {};
     if (projectUrl)
         update.projectUrl = projectUrl;
     if (projectId)
         update.projectId = projectId;
-    if (apiKey)
+    if (apiKey) {
         update.apiKey = apiKey;
+        // A hand-supplied key has no known token id; drop any stale id so uninstall
+        // never tries to delete a different token by an id that no longer matches.
+        update.apiKeyId = null;
+    }
     if (oauth2ClientId)
         update.oauth2ClientId = oauth2ClientId;
-    if (userLogin !== undefined)
-        update.userLogin = userLogin;
     // A non-empty namespace sets the SubjectSet namespace; the empty string
     // (from --no-user-subject-namespace) clears it (null ⇒ delete the key).
     if (userSubjectNamespace !== undefined) {
@@ -243,7 +208,7 @@ function runConfigureCommand(binName, args) {
     // Configuring an actual connection (a slug-based URL, api key, or client id)
     // implies leaving audit-only mode. A bare project id is only an admin
     // identifier — it doesn't connect anything on its own — so it doesn't flip
-    // the flag; nor does a standalone user-login toggle.
+    // the flag.
     if (projectUrl || apiKey || oauth2ClientId)
         update.auditOnly = false;
     (0, config_js_1.saveConfig)(update);
@@ -257,13 +222,11 @@ function runConfigureCommand(binName, args) {
         console.log(`  API Key: (set)`);
     if (oauth2ClientId)
         console.log(`  OAuth2 Client ID: ${oauth2ClientId}`);
-    if (userLogin !== undefined)
-        console.log(`  User Login: ${userLogin ? "on" : "off"}`);
     if (userSubjectNamespace !== undefined)
         console.log(`  User subject namespace: ${userSubjectNamespace === "" ? "(cleared — direct subject id)" : userSubjectNamespace}`);
     console.log("");
     console.log("This configuration is shared across all Ory agent plugins.");
-    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY, ORY_OAUTH2_CLIENT_ID, ORY_USER_LOGIN) take precedence when set.");
+    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY, ORY_OAUTH2_CLIENT_ID) take precedence when set.");
 }
 /**
  * Print the "Configuration:" block showing Ory project URL and API key status.
@@ -280,7 +243,6 @@ function printOryConfig() {
     console.log(`  API Key:         ${resolved.apiKey ? "(set)" : "NOT SET"} [source: ${resolved.apiKeySource}]`);
     console.log(`  OAuth2 Client:   ${resolved.oauth2ClientId ?? "NOT SET"} [source: ${resolved.oauth2ClientIdSource}]`);
     console.log(`  Permission mode: ${resolved.permissionMode} [source: ${resolved.permissionModeSource}]`);
-    console.log(`  User login:      ${resolved.userLogin ? "on" : "off"} [source: ${resolved.userLoginSource}]`);
     console.log(`  Namespace:       ${namespace}`);
     console.log(`  User subject ns: ${resolved.userSubjectNamespace ?? "(direct subject id)"} [source: ${resolved.userSubjectNamespaceSource}]`);
 }
@@ -294,7 +256,6 @@ function printEnvironment() {
         ["ORY_PROJECT_URL", process.env.ORY_PROJECT_URL, false],
         ["ORY_SDK_URL", process.env.ORY_SDK_URL, false],
         ["ORY_PROJECT_ID", process.env.ORY_PROJECT_ID, false],
-        ["ORY_USER_LOGIN", process.env.ORY_USER_LOGIN, false],
         [
             "ORY_AGENT_API_KEY",
             process.env.ORY_AGENT_API_KEY ? "(set)" : undefined,

package/dist/client.d.ts

@@ -159,6 +159,37 @@ export declare class OryAgentClient {
         created: boolean;
         alreadyExisted: boolean;
     }>;
+    /**
+     * True if the *exact* relation tuple already exists in Keto. Queries the
+     * relation-tuple listing API filtered by the tuple's own coordinates
+     * (namespace/object/relation + subject), so — unlike `checkPermission` —
+     * it does not follow subject-set expansion: it answers "is this literal
+     * tuple stored?", not "does this permission resolve?". Throws a classified
+     * {@link OryError} if the query itself fails.
+     */
+    relationshipExists(check: PermissionCheck): Promise<boolean>;
+    /**
+     * Idempotent relationship write. Keto's create API is **not** idempotent —
+     * `PUT /admin/relation-tuples` inserts a fresh row on every call (each with
+     * a new primary key) and never returns 409, so calling `createRelationship`
+     * on repeated bootstraps / session starts accumulates duplicate tuples.
+     * This reads the exact tuple first (via {@link relationshipExists}) and only
+     * writes when it is absent — which also self-heals if the tuple was deleted
+     * out of band.
+     *
+     * If the existence probe itself fails, the tuple is left untouched (we do
+     * not write blind, to avoid re-introducing duplicates when the read path is
+     * misbehaving) and the classified error is returned as `probeError`. Callers
+     * that must guarantee the grant exists (e.g. install-time bootstrap) can
+     * fall back to {@link createRelationship} when `probeError` is set.
+     */
+    ensureRelationship(check: PermissionCheck, options?: {
+        spanAttributes?: Record<string, unknown>;
+    }): Promise<{
+        created: boolean;
+        alreadyExisted: boolean;
+        probeError?: OryError;
+    }>;
     /**
      * Delete a relation tuple in Keto. Missing tuples (404) are treated as
      * success so callers can call this idempotently when unwinding state.

package/dist/client.js

@@ -551,6 +551,64 @@ class OryAgentClient {
             throw oryErr;
         }
     }
+    /**
+     * True if the *exact* relation tuple already exists in Keto. Queries the
+     * relation-tuple listing API filtered by the tuple's own coordinates
+     * (namespace/object/relation + subject), so — unlike `checkPermission` —
+     * it does not follow subject-set expansion: it answers "is this literal
+     * tuple stored?", not "does this permission resolve?". Throws a classified
+     * {@link OryError} if the query itself fails.
+     */
+    async relationshipExists(check) {
+        try {
+            const response = await this.relationship.getRelationships({
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                ...(check.subjectId ? { subjectId: check.subjectId } : {}),
+                ...(check.subjectSet
+                    ? {
+                        subjectSetNamespace: check.subjectSet.namespace,
+                        subjectSetObject: check.subjectSet.object,
+                        subjectSetRelation: check.subjectSet.relation,
+                    }
+                    : {}),
+                pageSize: 1,
+            });
+            const tuples = response.data?.relation_tuples ?? [];
+            return tuples.length > 0;
+        }
+        catch (err) {
+            throw this.classifyError(err);
+        }
+    }
+    /**
+     * Idempotent relationship write. Keto's create API is **not** idempotent —
+     * `PUT /admin/relation-tuples` inserts a fresh row on every call (each with
+     * a new primary key) and never returns 409, so calling `createRelationship`
+     * on repeated bootstraps / session starts accumulates duplicate tuples.
+     * This reads the exact tuple first (via {@link relationshipExists}) and only
+     * writes when it is absent — which also self-heals if the tuple was deleted
+     * out of band.
+     *
+     * If the existence probe itself fails, the tuple is left untouched (we do
+     * not write blind, to avoid re-introducing duplicates when the read path is
+     * misbehaving) and the classified error is returned as `probeError`. Callers
+     * that must guarantee the grant exists (e.g. install-time bootstrap) can
+     * fall back to {@link createRelationship} when `probeError` is set.
+     */
+    async ensureRelationship(check, options) {
+        let exists;
+        try {
+            exists = await this.relationshipExists(check);
+        }
+        catch (err) {
+            return { created: false, alreadyExisted: false, probeError: err };
+        }
+        if (exists)
+            return { created: false, alreadyExisted: true };
+        return this.createRelationship(check, options);
+    }
     /**
      * Delete a relation tuple in Keto. Missing tuples (404) are treated as
      * success so callers can call this idempotently when unwinding state.