toolpass-client 0.11.3 → 0.13.0

package/README.md

@@ -48,7 +48,10 @@ Without a wrapper:
 ```ts
 const d = await tp.check("dana@example.com", "jira-main", "DELETE_ISSUES", "issue:PAY-123");
 d.decision, d.reason;   // "deny", "denied: ..."
+d.identity;             // the account the email resolved to (a GitHub login), "" if none
 await tp.require(...);  // rejects with PermissionDenied unless allow
+// The fifth argument: the user's groups, or { groups, fresh, token } (token: the user's own
+// ID token, for a connection that reads the groups from it: oidc_issuer).
 ```
 
 Framework examples: [examples/agent-ts](https://github.com/roee-hersh/toolpass/tree/main/examples/agent-ts).

package/dist/index.d.ts

@@ -38,13 +38,15 @@ export type DecisionValue = typeof ALLOW | typeof DENY | typeof UNKNOWN;
  * `decision` is `allow`, `deny` or `unknown`. `reason` is `"<code>: <text>"`
  * as toolpass sent it, or `"client_error: ..."` when the request never
  * produced a usable answer. `status` is the HTTP status, 0 when no response
- * arrived.
+ * arrived. `identity` is the account the user's email resolved to in the
+ * system (a GitHub login), "" when none was resolved.
  */
 export declare class Decision {
     readonly decision: DecisionValue;
     readonly reason: string;
     readonly status: number;
-    constructor(decision: DecisionValue, reason: string, status?: number);
+    readonly identity: string;
+    constructor(decision: DecisionValue, reason: string, status?: number, identity?: string);
     /** True only for a positive `allow`. `unknown` is not allowed. */
     get allowed(): boolean;
     /** The machine-readable code in front of the colon, e.g. `user_not_found`. */
@@ -89,8 +91,10 @@ export declare class Toolpass {
     /**
      * Ask toolpass. Never rejects on transport: every failure becomes an
      * `unknown` decision. The fifth argument is the user's groups, or an
-     * options object: `{ groups, fresh }`. Groups left out or null are
-     * omitted from the request.
+     * options object: `{ groups, fresh, token }`. Groups left out or null are
+     * omitted from the request. `token` is the user's own login token (an
+     * OIDC ID token), for a connection that reads the groups from it
+     * (`oidc_issuer`).
      *
      * `fresh: true` asks for an answer straight from the upstream system,
      * skipping toolpass's caches. Use it for destructive actions. It narrows
@@ -107,6 +111,8 @@ export declare class Toolpass {
 export interface CheckOptions {
     /** The user's groups; left out or null, none are sent. */
     groups?: readonly string[] | null;
+    /** The user's own login token (an OIDC ID token); left out or null, none is sent. */
+    token?: string | null;
     /** Skip toolpass's caches and ask the upstream system now. */
     fresh?: boolean;
 }

package/dist/index.js

@@ -38,16 +38,19 @@ export const UNKNOWN = "unknown";
  * `decision` is `allow`, `deny` or `unknown`. `reason` is `"<code>: <text>"`
  * as toolpass sent it, or `"client_error: ..."` when the request never
  * produced a usable answer. `status` is the HTTP status, 0 when no response
- * arrived.
+ * arrived. `identity` is the account the user's email resolved to in the
+ * system (a GitHub login), "" when none was resolved.
  */
 export class Decision {
     decision;
     reason;
     status;
-    constructor(decision, reason, status = 200) {
+    identity;
+    constructor(decision, reason, status = 200, identity = "") {
         this.decision = decision;
         this.reason = reason;
         this.status = status;
+        this.identity = identity;
         Object.freeze(this);
     }
     /** True only for a positive `allow`. `unknown` is not allowed. */
@@ -105,8 +108,10 @@ export class Toolpass {
     /**
      * Ask toolpass. Never rejects on transport: every failure becomes an
      * `unknown` decision. The fifth argument is the user's groups, or an
-     * options object: `{ groups, fresh }`. Groups left out or null are
-     * omitted from the request.
+     * options object: `{ groups, fresh, token }`. Groups left out or null are
+     * omitted from the request. `token` is the user's own login token (an
+     * OIDC ID token), for a connection that reads the groups from it
+     * (`oidc_issuer`).
      *
      * `fresh: true` asks for an answer straight from the upstream system,
      * skipping toolpass's caches. Use it for destructive actions. It narrows
@@ -114,7 +119,7 @@ export class Toolpass {
      * two; it does not close it.
      */
     async check(user, connection, action, resource, options) {
-        const { groups, fresh } = checkOptions(options);
+        const { groups, fresh, token } = checkOptions(options);
         const body = { user, connection, action, resource };
         if (groups != null) {
             body.groups = groupList(groups);
@@ -122,6 +127,9 @@ export class Toolpass {
         if (fresh) {
             body.fresh = true;
         }
+        if (token) {
+            body.token = token;
+        }
         let response;
         let raw;
         try {
@@ -203,28 +211,31 @@ function isLoopback(hostname) {
 }
 function checkOptions(o) {
     if (o == null) {
-        return { groups: null, fresh: false };
+        return { groups: null, fresh: false, token: "" };
     }
     if (Array.isArray(o)) {
-        return { groups: o, fresh: false };
+        return { groups: o, fresh: false, token: "" };
     }
     if (typeof o === "boolean") {
-        throw new TypeError("the fifth argument is the groups array or { groups, fresh }; pass { fresh: true } for a fresh check");
+        throw new TypeError("the fifth argument is the groups array or { groups, fresh, token }; pass { fresh: true } for a fresh check");
     }
     if (typeof o !== "object" || Symbol.iterator in o) {
         // A Set or another iterable of groups is not an array of them.
         throw new TypeError("groups must be an array of strings");
     }
     for (const key of Object.keys(o)) {
-        if (key !== "groups" && key !== "fresh") {
-            throw new TypeError(`unknown check option ${JSON.stringify(key)}; the options are groups and fresh`);
+        if (key !== "groups" && key !== "fresh" && key !== "token") {
+            throw new TypeError(`unknown check option ${JSON.stringify(key)}; the options are groups, fresh and token`);
         }
     }
     const opts = o;
     if (opts.fresh !== undefined && typeof opts.fresh !== "boolean") {
         throw new TypeError("fresh must be a boolean");
     }
-    return { groups: opts.groups ?? null, fresh: opts.fresh === true };
+    if (opts.token != null && typeof opts.token !== "string") {
+        throw new TypeError("token must be a string");
+    }
+    return { groups: opts.groups ?? null, fresh: opts.fresh === true, token: opts.token ?? "" };
 }
 function groupList(groups) {
     if (typeof groups === "string" || !Array.isArray(groups) || !groups.every((g) => typeof g === "string")) {
@@ -251,7 +262,7 @@ function parse(status, raw) {
     if (typeof data !== "object" || data === null || !("decision" in data)) {
         return new Decision(UNKNOWN, `client_error: unexpected response (HTTP ${status})`, status);
     }
-    const { decision, reason } = data;
+    const { decision, reason, identity } = data;
     if (decision !== ALLOW && decision !== DENY && decision !== UNKNOWN) {
         return new Decision(UNKNOWN, `client_error: unexpected decision ${JSON.stringify(decision)}`, status);
     }
@@ -259,7 +270,7 @@ function parse(status, raw) {
         // toolpass never allows with a non-200 status; do not trust a proxy that does.
         return new Decision(UNKNOWN, `client_error: allow with HTTP ${status}`, status);
     }
-    return new Decision(decision, reason === undefined ? "" : String(reason), status);
+    return new Decision(decision, reason === undefined ? "" : String(reason), status, typeof identity === "string" ? identity : "");
 }
 /**
  * Resolve a user or groups source now.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolpass-client",
-  "version": "0.11.3",
+  "version": "0.13.0",
   "description": "Check with toolpass whether a user may do something before your AI agent does it for them.",
   "keywords": [
     "ai-agents",