@wegooli/identity-delegation 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+/**
+ * 위임에 관한 값들. Identity 가 돌려주는 JSON 을 그대로 옮긴 모양이다.
+ */
+/** 위임장 — "에이전트 A 가 주체 P 를 대신해 무엇까지, 언제까지" */
+interface Grant {
+    id: string;
+    organizationId: string;
+    agentId: string;
+    /** `user` = 우리 로그인 사용자, `external_user` = 고객사가 서명해서 알려준 사람, `organization` = 조직 */
+    principalKind: 'user' | 'organization' | 'external_user';
+    principalId: string;
+    scope: string;
+    allowedAudiences: string[];
+    grantedVia: string;
+    version: number;
+    expiresAt: string;
+    revokedAt?: string | null;
+    revokedReason?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** 고객사 인증서버가 서명해서 알려준 사람. 우리 로그인 사용자가 아니다. */
+interface ExternalPrincipal {
+    id: string;
+    organizationId: string;
+    issuerDid: string;
+    subject: string;
+    email?: string;
+    displayName?: string;
+    lastAssertedAt: string;
+}
+/** 위임장을 만들 때 진술로 밝혀진 사람 (진술을 보냈을 때만 온다) */
+interface AssertedPrincipal {
+    id: string;
+    kind: string;
+    issuerDid: string;
+    subject: string;
+    email?: string;
+    displayName?: string;
+}
+interface EnsureGrantResult {
+    grant: Grant;
+    /** 처음 만들어졌으면 true, 이미 있던 것을 돌려받았으면 false */
+    created: boolean;
+    principal?: AssertedPrincipal;
+}
+/** 리소스 서버가 선언하는 권한 하나 */
+interface ResourceScope {
+    name: string;
+    /** 동의 화면에 그려질 문장. 1인칭 현재형으로 쓴다 — "내 문서를 읽습니다" */
+    displayName: string;
+    description?: string;
+    /** 되돌리기 어려운 권한. 화면이 눈에 띄게 그린다 */
+    isSensitive?: boolean;
+}
+interface ResourceServer {
+    id: string;
+    organizationId: string;
+    identifier: string;
+    displayName: string;
+    description?: string;
+    metadataUrl?: string;
+    isEnabled: boolean;
+    scopes: ResourceScope[];
+}
+/** 위임 토큰이 밝혀 준 것 */
+interface AgentCaller {
+    /** 이 요청의 결과에 책임지는 사람/조직 — 토큰의 `sub` */
+    principalId: string;
+    /** `user` / `organization` / `external_user`. 없을 수도 있다 */
+    principalKind?: string;
+    /** 실제로 요청을 보낸 에이전트 — 토큰의 `act.sub` */
+    agentId: string;
+    agentType?: string;
+    /** 책임 주체의 이메일. 고객사 진술에서 왔든 우리 표에서 왔든 모양이 같다 */
+    email?: string;
+    organizationId?: string;
+    /** 어느 위임장에서 나온 권한인가. 사고 뒤 "무엇이 허락돼 있었나" 의 근거 */
+    grantId: string;
+    grantVersion?: number;
+    scopes: string[];
+    /** 이 토큰이 향하도록 허락된 주소 */
+    audience: string[];
+    expiresAt: Date;
+    /** 이 권한이 위임장에 있는가 */
+    has(scope: string): boolean;
+    /** 원본 클레임. 위의 것으로 부족할 때만 본다 */
+    claims: Record<string, unknown>;
+}
+
+interface DelegationClientOptions {
+    /** Identity 주소. 예: `https://api.freezz.kr` */
+    baseUrl: string;
+    /** `sk_live_…` 비밀 키. **브라우저에 절대 넣지 않는다** */
+    secretKey: string;
+    /** 테스트나 프록시용. 기본은 전역 fetch */
+    fetch?: typeof globalThis.fetch;
+    /** 한 요청의 제한 시간(ms). 기본 10초 */
+    timeoutMs?: number;
+}
+interface EnsureGrantOptions {
+    agentId: string;
+    /**
+     * 우리 로그인을 쓰는 사람의 id. 자체 인증 고객이라면 이 대신
+     * `principalAssertion` 을 보낸다. **둘 중 정확히 하나**만 보낸다.
+     */
+    principalId?: string;
+    /**
+     * 고객사 인증서버가 서명한 진술. "지금 이 버튼을 누른 사람은 우리 직원
+     * 아무개다" 를 서명한 문서다. 만드는 법은 통합 문서를 참고한다.
+     */
+    principalAssertion?: string;
+    /** 공백으로 구분한 권한 이름. 리소스 서버가 선언한 것만 쓸 수 있다 */
+    scope: string;
+    /** 이 위임으로 받은 토큰이 향할 수 있는 서비스 주소 */
+    audience: string | string[];
+    /** 며칠 뒤 만료할지. 외부 주체는 최대 1일 */
+    expiresInDays?: number;
+    /** 절대 시각으로 주고 싶을 때 (RFC 3339) */
+    expiresAt?: string;
+    /** 화면에서 사람이 본 문구·시각 등. 그대로 보관된다 */
+    consentEvidence?: Record<string, unknown>;
+    /**
+     * 껐던 사람이 **화면에서 다시 동의를 눌렀을 때만** true 로 보낸다.
+     * 재시도 로직이 자동으로 붙이면 안 된다 — 그 순간 끄기가 의미를 잃는다.
+     */
+    reconsent?: boolean;
+    /** RFC 9396 — 금액 한도 같은, 권한 이름으로 표현 못 하는 제한 */
+    authorizationDetails?: unknown;
+}
+interface IssueTokenOptions {
+    grantId: string;
+    audience: string;
+    /** 위임장의 권한 중 일부만 원할 때. 비우면 위임장 전체 */
+    scope?: string;
+    /**
+     * 에이전트 자신의 머신 자격증명(ZITADEL 이 발급한 JWT). Identity 는 이 값으로
+     * "이 위임장이 정말 이 에이전트 것인가" 를 확인한다.
+     */
+    machineToken: string;
+    /** 키에 묶인 에이전트라면 DPoP 증명 */
+    dpopProof?: string;
+}
+interface IssuedToken {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    scope: string;
+}
+/**
+ * Identity 의 서버 간 API 를 감싼다.
+ *
+ * ── 왜 "끄기" 가 "켜기" 와 같은 자리에 있는가 ──────────────────────────────
+ *
+ * 이 라이브러리가 존재하는 이유의 절반은 `revoke` 다. 토큰 검사만 제공하고
+ * 위임 만들기를 각자 짜게 두면, 고객마다 다르게 짜게 되고 그중 몇은 반드시
+ * **끄는 자리가 빠진 채로** 나온다. 스페이스노트에서 실제로 그렇게 됐다 —
+ * "언제든 끌 수 있습니다" 라고 화면에 적어 두고, 끄는 버튼이 없었다.
+ *
+ * 그래서 `ensure` 와 `revoke` 는 같은 객체에 있고, 인자 수도 비슷하다.
+ * 켜는 코드를 쓴 사람이 끄는 코드를 못 찾는 일이 없게 하려는 것이다.
+ */
+declare class DelegationClient {
+    private readonly baseUrl;
+    private readonly secretKey;
+    private readonly doFetch;
+    private readonly timeoutMs;
+    constructor(options: DelegationClientOptions);
+    readonly grants: {
+        /**
+         * 사람이 스위치를 켰을 때 부른다. **같은 (에이전트, 사람) 조합으로 여러 번
+         * 불러도 위임장이 하나만 생긴다** — 사람은 스위치를 두 번 누르고, 위임장이
+         * 둘이면 끌 때 하나만 꺼서는 안 멈춘다.
+         *
+         * 외부 주체(자체 인증 고객의 직원)라면 **이 호출이 갱신도 겸한다.** 새
+         * 진술을 붙여 다시 부르면 만료일이 밀린다. 진술을 못 만들게 되면(퇴사)
+         * 아무도 아무것도 안 해도 위임장이 스스로 닫힌다.
+         */
+        ensure: (options: EnsureGrantOptions) => Promise<EnsureGrantResult>;
+        /** 이 에이전트가 들고 있는 위임장들. 끄기 화면이 그리는 목록이다. */
+        list: (options: {
+            agentId: string;
+        }) => Promise<Grant[]>;
+        /**
+         * 끈다. **다음 검증 시점에 바로** 먹는다 — 이미 나가 있는 토큰도 무효가 된다.
+         *
+         * 이유를 적어 두면 나중에 "왜 멈췄나" 에 답할 수 있다. 사람이 껐는지,
+         * 관리자가 껐는지, 사고 대응이었는지가 전부 다른 이야기다.
+         */
+        revoke: (grantId: string, reason?: string) => Promise<void>;
+    };
+    readonly externalPrincipals: {
+        /** 진술로 알게 된 사람들. 우리 로그인 사용자가 아니다. */
+        list: () => Promise<ExternalPrincipal[]>;
+    };
+    readonly resourceServers: {
+        /**
+         * 내 서비스가 받는 권한 이름과 그 뜻을 선언한다. 동의 화면이 이 문장을
+         * 그대로 그린다.
+         *
+         * 배포할 때마다 불러도 된다 — 주소가 같으면 행이 하나로 유지되고, 선언은
+         * 통째로 바뀐다. 권한 하나를 목록에서 빼면 그 권한은 더 이상 위임될 수 없다.
+         */
+        declare: (options: {
+            identifier: string;
+            displayName: string;
+            description?: string;
+            metadataUrl?: string;
+            scopes: ResourceScope[];
+        }) => Promise<ResourceServer>;
+        list: () => Promise<ResourceServer[]>;
+    };
+    /**
+     * 위임장을 짧은 수명의 토큰으로 바꾼다.
+     *
+     * 이 호출은 **에이전트 자신이** 한다. 에이전트의 머신 자격증명이 필요하고,
+     * Identity 는 그것이 이 위임장의 에이전트가 맞는지 확인한다 — 없으면 유효한
+     * 머신 토큰 하나로 시스템의 모든 위임장을 쓸 수 있게 된다.
+     */
+    issueAgentToken(options: IssueTokenOptions): Promise<IssuedToken>;
+    private request;
+    private send;
+}
+/** 위임을 만들고 거두는 서버용 클라이언트를 만든다. */
+declare function createDelegationClient(options: DelegationClientOptions): DelegationClient;
+
+interface TokenVerifierOptions {
+    /** Identity 주소. 토큰의 `iss` 와 정확히 같아야 한다 */
+    issuer: string;
+    /**
+     * **내 서비스의 주소.** 토큰의 `aud` 가 이것이어야 통과한다.
+     *
+     * 필수다. 빼면 다른 서비스용으로 발급된 토큰이 여기서도 통과하고, 그 순간
+     * 위임장의 "이 토큰은 어디로 갈 수 있다" 는 제한이 아무것도 막지 않게 된다.
+     */
+    audience: string;
+    /** 기본은 `<issuer>/.well-known/jwks.json` */
+    jwksUri?: string;
+    /**
+     * 매 요청마다 Identity 에 "이 위임이 아직 살아 있나" 를 묻는다.
+     *
+     * 안 물으면 취소를 토큰 수명(약 5분)만큼 늦게 본다. 계약서 발송처럼
+     * 되돌리기 어려운 동작 앞에서는 켠다. 화면 하나 그리는 데는 안 켜도 된다.
+     */
+    introspect?: boolean;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Identity 가 발급한 위임 토큰을 검사한다.
+ *
+ * 기존 로그인 토큰과 다른 점은 하나다. 이 토큰은 "누가 불렀는가" 뿐 아니라
+ * **"누구를 대신해서"** 를 담고 있다 (RFC 8693).
+ *
+ *   sub     = 책임 주체 — 이 요청의 결과에 책임지는 사람
+ *   act.sub = 행위자   — 실제로 요청을 보낸 에이전트
+ *
+ * 순서가 거꾸로 보이지만 그게 요점이다. **sub 으로 권한을 판단하던 기존 코드가
+ * 그대로 동작한다.** act 는 "사람이 아니라 기계가 했다" 를 기록에 남기고 싶을
+ * 때만 읽으면 된다.
+ *
+ * 그리고 그 사람이 우리 로그인 사용자든 고객사 직원이든 **토큰 모양이 같다.**
+ * 여기서 둘을 구별하는 분기를 쓸 일은 없다.
+ */
+declare class TokenVerifier {
+    private readonly issuer;
+    private readonly audience;
+    private readonly jwks;
+    private readonly introspectEnabled;
+    private readonly doFetch;
+    constructor(options: TokenVerifierOptions);
+    /**
+     * `Authorization` 헤더나 토큰 문자열을 받아 검사한다.
+     *
+     * 실패는 전부 {@link TokenRejected} 다. **거절 이유를 응답에 그대로 실어
+     * 보내지 않는다** — 어느 검사에서 걸렸는지 알려 주는 것은 공격자에게 다음
+     * 시도의 힌트를 주는 일이다. 이유는 로그에만 남긴다.
+     */
+    verify(authorizationOrToken: string): Promise<AgentCaller>;
+    /**
+     * Identity 에 위임장이 아직 살아 있는지 묻는다.
+     *
+     * **네트워크가 안 되면 통과시킨다.** 서명과 만료는 이미 확인했고, Identity 가
+     * 잠깐 안 뜬다고 정상 요청이 전부 막히는 편이 더 나쁘다. 확실히 거절된
+     * 경우(401·403)에만 막는다.
+     */
+    private stillLive;
+}
+/** 위임 토큰 검사기를 만든다. */
+declare function createTokenVerifier(options: TokenVerifierOptions): TokenVerifier;
+
+/**
+ * Identity 가 거절했을 때 던지는 오류.
+ *
+ * `code` 는 Identity 가 돌려준 기계용 값이고, `message` 는 사람이 읽을 값이다.
+ * 둘을 나눠 두는 이유는 하나다 — 어떤 거절은 재시도로 풀리지 않고 사람이 다시
+ * 눌러야 풀린다. 코드로 갈라야 그 둘을 구별할 수 있다.
+ */
+declare class DelegationError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: string;
+    constructor(status: number, code: string, message: string, details?: string);
+    /**
+     * 그 사람이 껐던 위임을 다시 만들려 했다는 뜻이다.
+     *
+     * 이건 오류가 아니라 **설계**다. 사람이 끈 위임을 백엔드가 조용히 다시 만들면
+     * 그 사람이 누른 스위치는 아무것도 안 한 게 된다. 다시 켜려면 화면에서 사람이
+     * 다시 동의를 누르고, 그 동의를 근거로 `reconsent: true` 를 보내야 한다.
+     */
+    get isRevokedByPrincipal(): boolean;
+    /** 진술이 거절됐다 — 서명·수신자·수명·발급자 중 하나가 조건을 못 맞췄다 */
+    get isAssertionRejected(): boolean;
+}
+/** 토큰 검사가 실패했을 때. 이유는 로그로만 남기고 호출자에게는 한 가지로 준다. */
+declare class TokenRejected extends Error {
+    /** 왜 거절됐는지. 응답에 그대로 실어 보내지 말 것 — 공격자에게 힌트가 된다. */
+    readonly reason: string;
+    /** 위임이 취소돼서 거절됐는가. 이건 401 이 아니라 403 이다. */
+    readonly revoked: boolean;
+    constructor(reason: string, revoked?: boolean);
+}
+
+export { type AgentCaller, type AssertedPrincipal, DelegationClient, type DelegationClientOptions, DelegationError, type EnsureGrantOptions, type EnsureGrantResult, type ExternalPrincipal, type Grant, type IssueTokenOptions, type IssuedToken, type ResourceScope, type ResourceServer, TokenRejected, TokenVerifier, type TokenVerifierOptions, createDelegationClient, createTokenVerifier };

package/dist/index.js

@@ -0,0 +1,356 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DelegationClient: () => DelegationClient,
+  DelegationError: () => DelegationError,
+  TokenRejected: () => TokenRejected,
+  TokenVerifier: () => TokenVerifier,
+  createDelegationClient: () => createDelegationClient,
+  createTokenVerifier: () => createTokenVerifier
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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
+var import_jose = require("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 = (0, import_jose.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 (0, import_jose.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 [];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DelegationClient,
+  DelegationError,
+  TokenRejected,
+  TokenVerifier,
+  createDelegationClient,
+  createTokenVerifier
+});