@wegooli/identity-delegation 0.2.0

package/dist/index.mjs

@@ -0,0 +1,324 @@
+// src/errors.ts
+var DelegationError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "DelegationError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+  /**
+   * 그 사람이 껐던 위임을 다시 만들려 했다는 뜻이다.
+   *
+   * 이건 오류가 아니라 **설계**다. 사람이 끈 위임을 백엔드가 조용히 다시 만들면
+   * 그 사람이 누른 스위치는 아무것도 안 한 게 된다. 다시 켜려면 화면에서 사람이
+   * 다시 동의를 누르고, 그 동의를 근거로 `reconsent: true` 를 보내야 한다.
+   */
+  get isRevokedByPrincipal() {
+    return this.code === "grant_revoked";
+  }
+  /** 진술이 거절됐다 — 서명·수신자·수명·발급자 중 하나가 조건을 못 맞췄다 */
+  get isAssertionRejected() {
+    return this.code.startsWith("assertion_") || this.code === "issuer_not_trusted";
+  }
+};
+var TokenRejected = class extends Error {
+  constructor(reason, revoked = false) {
+    super(`token rejected: ${reason}`);
+    this.name = "TokenRejected";
+    this.reason = reason;
+    this.revoked = revoked;
+  }
+};
+
+// src/client.ts
+var DelegationClient = class {
+  constructor(options) {
+    // ── 위임 ────────────────────────────────────────────────────────────────
+    this.grants = {
+      /**
+       * 사람이 스위치를 켰을 때 부른다. **같은 (에이전트, 사람) 조합으로 여러 번
+       * 불러도 위임장이 하나만 생긴다** — 사람은 스위치를 두 번 누르고, 위임장이
+       * 둘이면 끌 때 하나만 꺼서는 안 멈춘다.
+       *
+       * 외부 주체(자체 인증 고객의 직원)라면 **이 호출이 갱신도 겸한다.** 새
+       * 진술을 붙여 다시 부르면 만료일이 밀린다. 진술을 못 만들게 되면(퇴사)
+       * 아무도 아무것도 안 해도 위임장이 스스로 닫힌다.
+       */
+      // `async` 인 것이 중요하다. 인자 검사를 동기로 던지면
+      // `ensure(...).catch(handle)` 로 쓴 코드가 그 오류만 못 받는다 — 같은 함수가
+      // 어떤 실패는 던지고 어떤 실패는 거절하는 API 는 반드시 한쪽을 놓치게 한다.
+      ensure: async (options) => {
+        const hasId = Boolean(options.principalId);
+        const hasAssertion = Boolean(options.principalAssertion);
+        if (hasId === hasAssertion) {
+          throw new Error(
+            "principalId (\uC6B0\uB9AC \uB85C\uADF8\uC778 \uC0AC\uC6A9\uC790) \uB610\uB294 principalAssertion (\uACE0\uAC1D\uC0AC\uAC00 \uC11C\uBA85\uD55C \uC9C4\uC220) \uC911 \uC815\uD655\uD788 \uD558\uB098\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4"
+          );
+        }
+        return this.request("POST", "/v1/agent-grants", {
+          agentId: options.agentId,
+          principalId: options.principalId,
+          principalAssertion: options.principalAssertion,
+          scope: options.scope,
+          allowedAudiences: Array.isArray(options.audience) ? options.audience : [options.audience],
+          expiresInDays: options.expiresInDays,
+          expiresAt: options.expiresAt,
+          consentEvidence: options.consentEvidence,
+          reconsent: options.reconsent,
+          authorizationDetails: options.authorizationDetails
+        });
+      },
+      /** 이 에이전트가 들고 있는 위임장들. 끄기 화면이 그리는 목록이다. */
+      list: async (options) => {
+        const out = await this.request(
+          "GET",
+          `/v1/agent-grants?agentId=${encodeURIComponent(options.agentId)}`
+        );
+        return out.grants ?? [];
+      },
+      /**
+       * 끈다. **다음 검증 시점에 바로** 먹는다 — 이미 나가 있는 토큰도 무효가 된다.
+       *
+       * 이유를 적어 두면 나중에 "왜 멈췄나" 에 답할 수 있다. 사람이 껐는지,
+       * 관리자가 껐는지, 사고 대응이었는지가 전부 다른 이야기다.
+       */
+      revoke: (grantId, reason) => this.request("POST", `/v1/agent-grants/${encodeURIComponent(grantId)}/revoke`, {
+        reason
+      })
+    };
+    // ── 외부 주체 ────────────────────────────────────────────────────────────
+    this.externalPrincipals = {
+      /** 진술로 알게 된 사람들. 우리 로그인 사용자가 아니다. */
+      list: async () => {
+        const out = await this.request(
+          "GET",
+          "/v1/external-principals"
+        );
+        return out.externalPrincipals ?? [];
+      }
+    };
+    // ── 내 서비스의 권한 어휘 ────────────────────────────────────────────────
+    this.resourceServers = {
+      /**
+       * 내 서비스가 받는 권한 이름과 그 뜻을 선언한다. 동의 화면이 이 문장을
+       * 그대로 그린다.
+       *
+       * 배포할 때마다 불러도 된다 — 주소가 같으면 행이 하나로 유지되고, 선언은
+       * 통째로 바뀐다. 권한 하나를 목록에서 빼면 그 권한은 더 이상 위임될 수 없다.
+       */
+      declare: async (options) => {
+        const out = await this.request(
+          "PUT",
+          "/v1/resource-servers",
+          options
+        );
+        return out.resourceServer;
+      },
+      list: async () => {
+        const out = await this.request(
+          "GET",
+          "/v1/resource-servers"
+        );
+        return out.resourceServers ?? [];
+      }
+    };
+    if (typeof window !== "undefined" && typeof document !== "undefined") {
+      throw new Error(
+        "@wegooli/identity-delegation \uC740 \uC11C\uBC84\uC5D0\uC11C\uB9CC \uC501\uB2C8\uB2E4. sk_ \uBE44\uBC00 \uD0A4\uAC00 \uBE0C\uB77C\uC6B0\uC800\uB85C \uB098\uAC00\uBA74 \uC774 \uC870\uC9C1\uC758 \uBAA8\uB4E0 \uC704\uC784\uC744 \uB204\uAD6C\uB098 \uB9CC\uB4E4\uACE0 \uC9C0\uC6B8 \uC218 \uC788\uC2B5\uB2C8\uB2E4."
+      );
+    }
+    if (!options.baseUrl) throw new Error("baseUrl \uC774 \uD544\uC694\uD569\uB2C8\uB2E4");
+    if (!options.secretKey?.startsWith("sk_")) {
+      throw new Error("secretKey \uB294 sk_ \uB85C \uC2DC\uC791\uD558\uB294 \uBE44\uBC00 \uD0A4\uC5EC\uC57C \uD569\uB2C8\uB2E4 (pk_ \uB294 \uACF5\uAC1C \uD0A4\uC785\uB2C8\uB2E4)");
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.secretKey = options.secretKey;
+    this.doFetch = options.fetch ?? globalThis.fetch;
+    this.timeoutMs = options.timeoutMs ?? 1e4;
+  }
+  // ── 토큰 ────────────────────────────────────────────────────────────────
+  /**
+   * 위임장을 짧은 수명의 토큰으로 바꾼다.
+   *
+   * 이 호출은 **에이전트 자신이** 한다. 에이전트의 머신 자격증명이 필요하고,
+   * Identity 는 그것이 이 위임장의 에이전트가 맞는지 확인한다 — 없으면 유효한
+   * 머신 토큰 하나로 시스템의 모든 위임장을 쓸 수 있게 된다.
+   */
+  async issueAgentToken(options) {
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${options.machineToken}`
+    };
+    if (options.dpopProof) headers.DPoP = options.dpopProof;
+    return this.send("POST", "/api/agent/token", headers, {
+      grantId: options.grantId,
+      audience: options.audience,
+      scope: options.scope
+    });
+  }
+  // ── 내부 ────────────────────────────────────────────────────────────────
+  request(method, path, body) {
+    return this.send(
+      method,
+      path,
+      {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.secretKey}`
+      },
+      body
+    );
+  }
+  async send(method, path, headers, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.doFetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === void 0 ? void 0 : JSON.stringify(stripUndefined(body)),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status === 204) return void 0;
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = text ? JSON.parse(text) : {};
+    } catch {
+      parsed = {};
+    }
+    if (!response.ok) {
+      const payload = parsed;
+      throw new DelegationError(
+        response.status,
+        payload.error ?? "unknown_error",
+        payload.details ?? payload.error_description ?? `${method} ${path} \u2192 ${response.status}`,
+        payload.details
+      );
+    }
+    return parsed;
+  }
+};
+function stripUndefined(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (v !== void 0) out[k] = v;
+  }
+  return out;
+}
+function createDelegationClient(options) {
+  return new DelegationClient(options);
+}
+
+// src/verifier.ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+var TokenVerifier = class {
+  constructor(options) {
+    if (!options.issuer) throw new Error("issuer \uAC00 \uD544\uC694\uD569\uB2C8\uB2E4");
+    if (!options.audience) {
+      throw new Error(
+        "audience \uAC00 \uD544\uC694\uD569\uB2C8\uB2E4 \u2014 \uB0B4 \uC11C\uBE44\uC2A4 \uC8FC\uC18C\uC785\uB2C8\uB2E4. \uBE7C\uBA74 \uB2E4\uB978 \uC11C\uBE44\uC2A4\uC6A9 \uD1A0\uD070\uB3C4 \uC5EC\uAE30\uC11C \uD1B5\uACFC\uD569\uB2C8\uB2E4."
+      );
+    }
+    this.issuer = options.issuer.replace(/\/+$/, "");
+    this.audience = options.audience.replace(/\/+$/, "");
+    this.introspectEnabled = options.introspect ?? false;
+    this.doFetch = options.fetch ?? globalThis.fetch;
+    this.jwks = createRemoteJWKSet(new URL(options.jwksUri ?? `${this.issuer}/.well-known/jwks.json`));
+  }
+  /**
+   * `Authorization` 헤더나 토큰 문자열을 받아 검사한다.
+   *
+   * 실패는 전부 {@link TokenRejected} 다. **거절 이유를 응답에 그대로 실어
+   * 보내지 않는다** — 어느 검사에서 걸렸는지 알려 주는 것은 공격자에게 다음
+   * 시도의 힌트를 주는 일이다. 이유는 로그에만 남긴다.
+   */
+  async verify(authorizationOrToken) {
+    const token = stripScheme(authorizationOrToken);
+    if (!token) throw new TokenRejected("no token");
+    let payload;
+    try {
+      const verified = await jwtVerify(token, this.jwks, {
+        issuer: this.issuer,
+        audience: this.audience,
+        algorithms: ["ES256"]
+      });
+      payload = verified.payload;
+    } catch (err) {
+      throw new TokenRejected(err.message);
+    }
+    const principalId = typeof payload.sub === "string" ? payload.sub : "";
+    const act = payload["act"] ?? null;
+    const agentId = act && typeof act.sub === "string" ? act.sub : "";
+    const grantId = typeof payload["gnt"] === "string" ? payload["gnt"] : "";
+    if (!principalId || !agentId || !grantId) {
+      throw new TokenRejected("sub / act.sub / gnt \uC911 \uBE60\uC9C4 \uAC83\uC774 \uC788\uC5B4 \uC704\uC784 \uD1A0\uD070\uC774 \uC544\uB2C8\uB2E4");
+    }
+    if (this.introspectEnabled && !await this.stillLive(token)) {
+      throw new TokenRejected("\uC704\uC784\uC774 \uCDE8\uC18C\uB410\uB2E4", true);
+    }
+    const scopes = typeof payload["scope"] === "string" ? payload["scope"].split(/\s+/).filter(Boolean) : [];
+    return {
+      principalId,
+      principalKind: typeof payload["principal_kind"] === "string" ? payload["principal_kind"] : void 0,
+      agentId,
+      agentType: act && typeof act.type === "string" ? act.type : void 0,
+      email: typeof payload["email"] === "string" ? payload["email"] : void 0,
+      organizationId: typeof payload["org"] === "string" ? payload["org"] : void 0,
+      grantId,
+      grantVersion: typeof payload["gv"] === "number" ? payload["gv"] : void 0,
+      scopes,
+      audience: normalizeAudience(payload.aud),
+      expiresAt: new Date((payload.exp ?? 0) * 1e3),
+      has: (scope) => scopes.includes(scope),
+      claims: payload
+    };
+  }
+  /**
+   * Identity 에 위임장이 아직 살아 있는지 묻는다.
+   *
+   * **네트워크가 안 되면 통과시킨다.** 서명과 만료는 이미 확인했고, Identity 가
+   * 잠깐 안 뜬다고 정상 요청이 전부 막히는 편이 더 나쁘다. 확실히 거절된
+   * 경우(401·403)에만 막는다.
+   */
+  async stillLive(token) {
+    try {
+      const response = await this.doFetch(`${this.issuer}/api/agent/verify`, {
+        headers: { Authorization: `Bearer ${token}` },
+        cache: "no-store"
+      });
+      return !(response.status === 401 || response.status === 403);
+    } catch {
+      return true;
+    }
+  }
+};
+function createTokenVerifier(options) {
+  return new TokenVerifier(options);
+}
+function stripScheme(value) {
+  const trimmed = value.trim();
+  const lower = trimmed.toLowerCase();
+  for (const scheme of ["bearer ", "dpop "]) {
+    if (lower.startsWith(scheme)) return trimmed.slice(scheme.length).trim();
+  }
+  return trimmed;
+}
+function normalizeAudience(aud) {
+  if (typeof aud === "string") return [aud];
+  if (Array.isArray(aud)) return aud.filter((a) => typeof a === "string");
+  return [];
+}
+export {
+  DelegationClient,
+  DelegationError,
+  TokenRejected,
+  TokenVerifier,
+  createDelegationClient,
+  createTokenVerifier
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@wegooli/identity-delegation",
+  "version": "0.2.0",
+  "description": "위임 만들기·거두기·토큰 받기·토큰 검사 — 서버에서 쓰는 라이브러리",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "jose": "^5.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wegooli/javascript.git",
+    "directory": "packages/identity-delegation"
+  },
+  "homepage": "https://github.com/wegooli/javascript/tree/main/packages/identity-delegation#readme",
+  "bugs": "https://github.com/wegooli/javascript/issues",
+  "keywords": [
+    "identity",
+    "delegation",
+    "agent",
+    "oauth",
+    "mcp",
+    "server"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run"
+  }
+}