@authyon/server 0.1.5

package/dist/index.js

@@ -0,0 +1,477 @@
+// src/errors.ts
+var AuthyonError = class extends Error {
+  constructor(status, body) {
+    super(body.detail ?? body.title ?? `Authyon request failed with status ${status}`);
+    this.name = "AuthyonError";
+    this.status = status;
+    this.code = body.code ?? "unknown";
+    this.title = body.title ?? "Error";
+    this.detail = body.detail;
+  }
+  is(code) {
+    return this.code === code;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.authyon.com";
+var EXPIRY_SKEW_MS = 3e4;
+function toQuery(params = {}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0) query.set(key, String(value));
+  }
+  const qs = query.toString();
+  return qs ? `?${qs}` : "";
+}
+var AuthyonServerClient = class {
+  constructor(options = {}) {
+    this.environmentToken = null;
+    this.environmentTokenInFlight = null;
+    // ── Discovery ──────────────────────────────────────────────────────────────
+    this.discovery = {
+      /** GET /.well-known/jwks.json — the environment's public signing keys. */
+      jwks: (publishableKey) => this.request(
+        publishableKey ? `/.well-known/${encodeURIComponent(publishableKey)}/jwks.json` : "/.well-known/jwks.json"
+      ),
+      /** GET /.well-known/openid-configuration — OIDC discovery document. */
+      openidConfiguration: (publishableKey) => this.request(
+        publishableKey ? `/.well-known/${encodeURIComponent(publishableKey)}/openid-configuration` : "/.well-known/openid-configuration"
+      )
+    };
+    // ── Environment-level machine auth ───────────────────────────────────────
+    this.environmentAuth = {
+      /** POST /env/oauth/token — exchanges environment client credentials for an access token. */
+      token: (credentials) => this.request("/env/oauth/token", {
+        method: "POST",
+        body: {
+          grant_type: "client_credentials",
+          client_id: credentials.clientId,
+          client_secret: credentials.clientSecret
+        }
+      })
+    };
+    // ── Tenant-level machine auth ─────────────────────────────────────────────
+    this.tenantAuth = {
+      /** POST /tenant/oauth/token — exchanges a tenant's client credentials for a scoped access token. */
+      token: (credentials) => this.request("/tenant/oauth/token", {
+        method: "POST",
+        body: {
+          grant_type: "client_credentials",
+          client_id: credentials.clientId,
+          client_secret: credentials.clientSecret
+        }
+      })
+    };
+    // ── Environment management (users, tenants, roles, permissions, audit) ───
+    this.environment = {
+      users: {
+        /** GET /env/users — paginated list of users in the environment. */
+        list: (params = {}) => this.request("/env/users", { envBearer: true, query: params }),
+        /** POST /env/users — create a user in the environment; returns only the new id. */
+        create: (input) => this.request("/env/users", { method: "POST", envBearer: true, body: input }),
+        /** GET /env/users/{userId} — fetch an environment user by id. */
+        get: (userId) => this.request(`/env/users/${encodeURIComponent(userId)}`, { envBearer: true }),
+        /** POST /env/users/{userId}/roles — grant a role to an environment user. */
+        assignRole: (userId, role) => this.request(`/env/users/${encodeURIComponent(userId)}/roles`, {
+          method: "POST",
+          envBearer: true,
+          body: { role }
+        }),
+        /** DELETE /env/users/{userId}/roles/{role} — revoke a role from an environment user. */
+        removeRole: (userId, role) => this.request(`/env/users/${encodeURIComponent(userId)}/roles/${encodeURIComponent(role)}`, {
+          method: "DELETE",
+          envBearer: true
+        }),
+        /** POST /env/users/{userId}/permissions — grant a direct permission to an environment user. */
+        grantPermission: (userId, permission) => this.request(`/env/users/${encodeURIComponent(userId)}/permissions`, {
+          method: "POST",
+          envBearer: true,
+          body: { permission }
+        }),
+        /** DELETE /env/users/{userId}/permissions/{permission} — revoke a direct permission. */
+        revokePermission: (userId, permission) => this.request(
+          `/env/users/${encodeURIComponent(userId)}/permissions/${encodeURIComponent(permission)}`,
+          { method: "DELETE", envBearer: true }
+        ),
+        /** POST /env/users/{userId}/unlock — clears an environment user's lockout. */
+        unlock: (userId, reason) => this.request(`/env/users/${encodeURIComponent(userId)}/unlock`, {
+          method: "POST",
+          envBearer: true,
+          body: { reason }
+        }),
+        /** POST /env/users/{userId}/password — sets a new password for the user. */
+        setPassword: (userId, newPassword, reason) => this.request(`/env/users/${encodeURIComponent(userId)}/password`, {
+          method: "POST",
+          envBearer: true,
+          body: { newPassword, reason }
+        }),
+        /** POST /env/users/{userId}/sessions/revoke-all — revokes every session the user has. */
+        revokeSessions: (userId, reason) => this.request(`/env/users/${encodeURIComponent(userId)}/sessions/revoke-all`, {
+          method: "POST",
+          envBearer: true,
+          body: { reason }
+        }),
+        /** DELETE /env/users/{userId}/sessions/{sessionId} — revokes a single session. */
+        revokeSession: (userId, sessionId, reason) => this.request(
+          `/env/users/${encodeURIComponent(userId)}/sessions/${encodeURIComponent(sessionId)}`,
+          { method: "DELETE", envBearer: true, query: { reason } }
+        ),
+        /** POST /env/users/{userId}/disable — bans the user indefinitely; revokes live sessions. */
+        disable: (userId, reason) => this.request(`/env/users/${encodeURIComponent(userId)}/disable`, {
+          method: "POST",
+          envBearer: true,
+          body: { reason }
+        }),
+        /** POST /env/users/{userId}/enable — lifts a ban. */
+        enable: (userId, reason) => this.request(`/env/users/${encodeURIComponent(userId)}/enable`, {
+          method: "POST",
+          envBearer: true,
+          body: { reason }
+        }),
+        /** POST /env/users/{userId}/suspend — blocks the user temporarily; clears itself after `durationMinutes`. */
+        suspend: (userId, durationMinutes, reason) => this.request(`/env/users/${encodeURIComponent(userId)}/suspend`, {
+          method: "POST",
+          envBearer: true,
+          body: { durationMinutes, reason }
+        }),
+        /** POST /env/users/{userId}/unsuspend — lifts a suspension early. */
+        unsuspend: (userId, reason) => this.request(`/env/users/${encodeURIComponent(userId)}/unsuspend`, {
+          method: "POST",
+          envBearer: true,
+          body: { reason }
+        }),
+        /** POST /env/users/{userId}/tenants — adds an environment user to a tenant. */
+        assignTenant: (userId, tenantId, roles) => this.request(`/env/users/${encodeURIComponent(userId)}/tenants`, {
+          method: "POST",
+          envBearer: true,
+          body: { tenantId, roles }
+        }),
+        /** DELETE /env/users/{userId}/tenants/{tenantId} — removes an environment user from a tenant. */
+        removeTenant: (userId, tenantId) => this.request(
+          `/env/users/${encodeURIComponent(userId)}/tenants/${encodeURIComponent(tenantId)}`,
+          { method: "DELETE", envBearer: true }
+        )
+      },
+      tenants: {
+        /** GET /env/tenants — list tenants in the environment. */
+        list: () => this.request("/env/tenants", { envBearer: true }),
+        /** POST /env/tenants — create a tenant in the environment. */
+        create: (input) => this.request("/env/tenants", { method: "POST", envBearer: true, body: input }),
+        /** GET /env/tenants/{tenantId} — fetch a tenant by id. */
+        get: (tenantId) => this.request(`/env/tenants/${encodeURIComponent(tenantId)}`, { envBearer: true }),
+        /** PUT /env/tenants/{tenantId} — update a tenant. */
+        update: (tenantId, input) => this.request(`/env/tenants/${encodeURIComponent(tenantId)}`, {
+          method: "PUT",
+          envBearer: true,
+          body: input
+        }),
+        /** DELETE /env/tenants/{tenantId} — delete a tenant. */
+        delete: (tenantId) => this.request(`/env/tenants/${encodeURIComponent(tenantId)}`, {
+          method: "DELETE",
+          envBearer: true
+        }),
+        members: {
+          /**
+           * GET /env/tenants/{tenantId}/members — a tenant's members as full
+           * user records. Confirmed live: a bare array (unlike
+           * `environment.users.list()`, this one does NOT paginate despite
+           * accepting `skip`/`take`), with the same shape
+           * `environment.users.list()` items have.
+           */
+          list: (tenantId, params = {}) => this.request(`/env/tenants/${encodeURIComponent(tenantId)}/members`, {
+            envBearer: true,
+            query: params
+          }),
+          /** POST /env/tenants/{tenantId}/members — add a member to a tenant. */
+          add: (tenantId, userId, roles) => this.request(`/env/tenants/${encodeURIComponent(tenantId)}/members`, {
+            method: "POST",
+            envBearer: true,
+            body: { userId, roles }
+          }),
+          /** DELETE /env/tenants/{tenantId}/members/{userId} — remove a member from a tenant. */
+          remove: (tenantId, userId) => this.request(
+            `/env/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}`,
+            { method: "DELETE", envBearer: true }
+          ),
+          /** POST /env/tenants/{tenantId}/members/{userId}/roles — grant a tenant role to a member. */
+          assignRole: (tenantId, userId, role) => this.request(
+            `/env/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}/roles`,
+            { method: "POST", envBearer: true, body: { role } }
+          ),
+          /** DELETE .../members/{userId}/roles/{role} — revoke a tenant role from a member. */
+          removeRole: (tenantId, userId, role) => this.request(
+            `/env/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}/roles/${encodeURIComponent(role)}`,
+            { method: "DELETE", envBearer: true }
+          ),
+          /** POST .../members/{userId}/permissions — grant a permission to a tenant member. */
+          grantPermission: (tenantId, userId, permission) => this.request(
+            `/env/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}/permissions`,
+            { method: "POST", envBearer: true, body: { permission } }
+          ),
+          /** DELETE .../members/{userId}/permissions/{permission} — revoke a permission from a tenant member. */
+          revokePermission: (tenantId, userId, permission) => this.request(
+            `/env/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}/permissions/${encodeURIComponent(permission)}`,
+            { method: "DELETE", envBearer: true }
+          )
+        },
+        roles: {
+          /** GET /env/tenants/{tenantId}/roles — list a tenant's roles. */
+          list: (tenantId) => this.request(`/env/tenants/${encodeURIComponent(tenantId)}/roles`, { envBearer: true }),
+          /** POST /env/tenants/{tenantId}/roles — create a tenant role. */
+          create: (tenantId, input) => this.request(`/env/tenants/${encodeURIComponent(tenantId)}/roles`, {
+            method: "POST",
+            envBearer: true,
+            body: input
+          }),
+          /** GET /env/tenants/{tenantId}/roles/{roleId} — fetch a tenant role by id. */
+          get: (tenantId, roleId) => this.request(
+            `/env/tenants/${encodeURIComponent(tenantId)}/roles/${encodeURIComponent(roleId)}`,
+            { envBearer: true }
+          ),
+          /** PUT /env/tenants/{tenantId}/roles/{roleId} — update a tenant role. */
+          update: (tenantId, roleId, input) => this.request(
+            `/env/tenants/${encodeURIComponent(tenantId)}/roles/${encodeURIComponent(roleId)}`,
+            { method: "PUT", envBearer: true, body: input }
+          ),
+          /** DELETE /env/tenants/{tenantId}/roles/{roleId} — delete a tenant role. */
+          delete: (tenantId, roleId) => this.request(
+            `/env/tenants/${encodeURIComponent(tenantId)}/roles/${encodeURIComponent(roleId)}`,
+            { method: "DELETE", envBearer: true }
+          )
+        }
+      },
+      roles: {
+        /** GET /env/roles — environment-level roles, grouped into custom and system-defined. */
+        list: () => this.request("/env/roles", { envBearer: true }),
+        /** POST /env/roles — create an environment-level role. */
+        create: (input) => this.request("/env/roles", { method: "POST", envBearer: true, body: input }),
+        /** PUT /env/roles/{roleId} — update an environment-level role. */
+        update: (roleId, input) => this.request(`/env/roles/${encodeURIComponent(roleId)}`, {
+          method: "PUT",
+          envBearer: true,
+          body: input
+        }),
+        /** DELETE /env/roles/{roleId} — delete an environment-level role. */
+        delete: (roleId) => this.request(`/env/roles/${encodeURIComponent(roleId)}`, {
+          method: "DELETE",
+          envBearer: true
+        })
+      },
+      permissions: {
+        /** GET /env/permissions — environment-level permissions, grouped by the role they're attached to. */
+        list: () => this.request("/env/permissions", { envBearer: true }),
+        /** POST /env/permissions — create an environment-level permission. */
+        create: (input) => this.request("/env/permissions", { method: "POST", envBearer: true, body: input }),
+        /** PUT /env/permissions/{permissionId} — update an environment-level permission. */
+        update: (permissionId, description) => this.request(`/env/permissions/${encodeURIComponent(permissionId)}`, {
+          method: "PUT",
+          envBearer: true,
+          body: { description }
+        }),
+        /** DELETE /env/permissions/{permissionId} — delete an environment-level permission. */
+        delete: (permissionId) => this.request(`/env/permissions/${encodeURIComponent(permissionId)}`, {
+          method: "DELETE",
+          envBearer: true
+        }),
+        /** GET /permissions/reserved — reserved permission names you can't redefine. */
+        reserved: () => this.request("/permissions/reserved", { envBearer: true })
+      },
+      audit: {
+        /** GET /env/audit — paginated list of the environment's audit events. */
+        list: (params = {}) => this.request("/env/audit", { envBearer: true, query: params }),
+        /** GET /env/audit/login-activity — paginated login activity in the environment. */
+        loginActivity: (params = {}) => this.request("/env/audit/login-activity", { envBearer: true, query: params })
+      }
+    };
+    // ── Generic permission grants ─────────────────────────────────────────────
+    this.permissions = {
+      /** POST /users/{userId}/permissions — grant a permission directly to a user. */
+      grant: (userId, permission) => this.request(`/users/${encodeURIComponent(userId)}/permissions`, {
+        method: "POST",
+        envBearer: true,
+        body: { permission }
+      }),
+      /** DELETE /users/{userId}/permissions/{permission} — revoke a permission from a user. */
+      revoke: (userId, permission) => this.request(
+        `/users/${encodeURIComponent(userId)}/permissions/${encodeURIComponent(permission)}`,
+        { method: "DELETE", envBearer: true }
+      )
+    };
+    this.envKey = options.envKey;
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = options.fetch ?? fetch.bind(globalThis);
+  }
+  async request(path, options = {}) {
+    const headers = { ...options.headers };
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    if (options.envBearer) {
+      headers.Authorization = `Bearer ${await this.getEnvironmentAccessToken()}`;
+    }
+    if (this.envKey) headers["X-Authyon-Environment"] = this.envKey;
+    const response = await this.fetchImpl(`${this.baseUrl}${path}${toQuery(options.query)}`, {
+      method: options.method ?? "GET",
+      headers,
+      body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
+    });
+    if (!response.ok) {
+      let body = {};
+      try {
+        body = await response.json();
+      } catch {
+      }
+      throw new AuthyonError(response.status, body);
+    }
+    if (response.status === 204) return void 0;
+    return await response.json();
+  }
+  /** Mints (and caches) an environment access token from `clientId`/`clientSecret`. */
+  async getEnvironmentAccessToken() {
+    if (this.environmentToken && Date.now() < this.environmentToken.expiresAt - EXPIRY_SKEW_MS) {
+      return this.environmentToken.accessToken;
+    }
+    if (this.environmentTokenInFlight) return this.environmentTokenInFlight;
+    if (!this.clientId || !this.clientSecret) {
+      throw new Error(
+        "Authyon: `clientId`/`clientSecret` are required for environment management calls (mint a pair in the console, under the environment's OAuth clients)."
+      );
+    }
+    this.environmentTokenInFlight = this.environmentAuth.token({ clientId: this.clientId, clientSecret: this.clientSecret }).then((token) => {
+      this.environmentToken = {
+        accessToken: token.access_token,
+        expiresAt: Date.now() + token.expires_in * 1e3
+      };
+      return token.access_token;
+    }).finally(() => {
+      this.environmentTokenInFlight = null;
+    });
+    return this.environmentTokenInFlight;
+  }
+  // ── Token verification ────────────────────────────────────────────────────
+  //
+  // Per RFC 7662 §2.1, the CALLER must authenticate here too — the token
+  // being inspected sits in the body, but the request itself needs an
+  // environment (or tenant) client-credentials bearer token, same as
+  // `environment.*`. Confirmed against the live API: calling either
+  // endpoint with only the `X-Authyon-Environment` header (no bearer)
+  // returns 401 with `WWW-Authenticate: Bearer`.
+  /** POST /auth/introspect — lightweight token introspection (RFC 7662). */
+  introspect(token) {
+    return this.request("/auth/introspect", { method: "POST", envBearer: true, body: { token } });
+  }
+  /** POST /auth/validate — recommended: cross-checks DB state, catches revocation immediately. */
+  async validate(token) {
+    const raw = await this.request("/auth/validate", { method: "POST", envBearer: true, body: { token } });
+    return { valid: raw.valid, reason: raw.reason ?? null, user: raw.profile };
+  }
+  /**
+   * Scopes a client to a single tenant's OAuth credentials — mints and
+   * caches its access token independently of the environment plane. Use
+   * this for the `TenantManagement` endpoints (`/tenant/...`), which act on
+   * "the token's tenant" rather than one you pass by id.
+   */
+  tenant(credentials) {
+    return new TenantScopedClient(this, credentials);
+  }
+  /** @internal used by {@link TenantScopedClient} to share the base URL/fetch/error handling. */
+  _requestAsTenant(accessToken, path, options = {}) {
+    return this.request(path, {
+      ...options,
+      headers: { ...options.headers, Authorization: `Bearer ${accessToken}` },
+      envBearer: false
+    });
+  }
+};
+var TenantScopedClient = class {
+  constructor(server, credentials) {
+    this.token = null;
+    this.tokenInFlight = null;
+    this.members = {
+      /**
+       * GET /tenant/members — members of the token's tenant.
+       *
+       * ⚠️ Inferred, not confirmed live (no tenant client credentials
+       * available to exchange for a scoped token) — assumed to share
+       * `/env/tenants/{id}/members`'s confirmed shape (bare array of full
+       * user records), since both are the "admin" member listing as opposed
+       * to `/auth/tenants/{id}/members`'s paginated, lightweight one.
+       */
+      list: (params = {}) => this.request("/tenant/members", { query: params }),
+      /** POST /tenant/members — add a member to the token's tenant. */
+      add: (userId, roles) => this.request("/tenant/members", { method: "POST", body: { userId, roles } }),
+      /** DELETE /tenant/members/{userId} — remove a member from the token's tenant. */
+      remove: (userId) => this.request(`/tenant/members/${encodeURIComponent(userId)}`, { method: "DELETE" }),
+      /** POST /tenant/members/{userId}/roles — grant a role to a member of the tenant. */
+      assignRole: (userId, role) => this.request(`/tenant/members/${encodeURIComponent(userId)}/roles`, {
+        method: "POST",
+        body: { role }
+      }),
+      /** DELETE /tenant/members/{userId}/roles/{role} — revoke a role from a member of the tenant. */
+      removeRole: (userId, role) => this.request(
+        `/tenant/members/${encodeURIComponent(userId)}/roles/${encodeURIComponent(role)}`,
+        { method: "DELETE" }
+      ),
+      /** POST /tenant/members/{userId}/permissions — grant a permission to a member of the tenant. */
+      grantPermission: (userId, permission) => this.request(`/tenant/members/${encodeURIComponent(userId)}/permissions`, {
+        method: "POST",
+        body: { permission }
+      }),
+      /** DELETE .../permissions/{permission} — revoke a permission from a member of the tenant. */
+      revokePermission: (userId, permission) => this.request(
+        `/tenant/members/${encodeURIComponent(userId)}/permissions/${encodeURIComponent(permission)}`,
+        { method: "DELETE" }
+      )
+    };
+    this.roles = {
+      /**
+       * GET /tenant/roles — roles in the token's tenant, grouped into custom
+       * and system-defined.
+       *
+       * ⚠️ Inferred, not confirmed live (the test environment had no tenants
+       * to exchange a scoped token for) — assumed to share `/env/roles`'
+       * grouped shape, since both operate on the same underlying role model.
+       */
+      list: () => this.request("/tenant/roles"),
+      /** POST /tenant/roles — create a role in the tenant. */
+      create: (input) => this.request("/tenant/roles", { method: "POST", body: input }),
+      /** GET /tenant/roles/{roleId} — fetch a tenant role by id. */
+      get: (roleId) => this.request(`/tenant/roles/${encodeURIComponent(roleId)}`),
+      /** PUT /tenant/roles/{roleId} — update a role in the tenant. */
+      update: (roleId, input) => this.request(`/tenant/roles/${encodeURIComponent(roleId)}`, { method: "PUT", body: input }),
+      /** DELETE /tenant/roles/{roleId} — delete a role in the tenant. */
+      delete: (roleId) => this.request(`/tenant/roles/${encodeURIComponent(roleId)}`, { method: "DELETE" })
+    };
+    this.server = server;
+    this.credentials = credentials;
+  }
+  async getAccessToken() {
+    if (this.token && Date.now() < this.token.expiresAt - EXPIRY_SKEW_MS) {
+      return this.token.accessToken;
+    }
+    if (this.tokenInFlight) return this.tokenInFlight;
+    this.tokenInFlight = this.server.tenantAuth.token(this.credentials).then((token) => {
+      this.token = {
+        accessToken: token.access_token,
+        expiresAt: Date.now() + token.expires_in * 1e3
+      };
+      return token.access_token;
+    }).finally(() => {
+      this.tokenInFlight = null;
+    });
+    return this.tokenInFlight;
+  }
+  async request(path, options = {}) {
+    return this.server._requestAsTenant(await this.getAccessToken(), path, options);
+  }
+};
+function createClient(options = {}) {
+  return new AuthyonServerClient(options);
+}
+export {
+  AuthyonError,
+  AuthyonServerClient,
+  TenantScopedClient,
+  createClient
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@authyon/server",
+  "version": "0.1.5",
+  "description": "Authyon SDK for backends — server-to-server organization/member management and access-token verification.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "authyon",
+    "auth",
+    "server-to-server",
+    "management-api",
+    "token-verification"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  }
+}