Accepting Agent Delegation

Setup Install & Initialize (resource server) 설치 & 초기화 (리소스 서버)

Verification is zero-dependency: it uses Node 18's built-in crypto (no jose, no jsonwebtoken) and requires Node 18+. Since v4, clientId/clientSecret/redirectUri are optional — a resource server that only calls verifyAgentToken() constructs with just authServerUrl. 검증은 의존성 0입니다 — Node 18 내장 crypto 만 사용하며(jose/jsonwebtoken 불필요) Node 18+ 가 필요합니다. v4 부터 clientId/clientSecret/redirectUri 는 선택이며, verifyAgentToken() 만 호출하는 리소스 서버는 authServerUrl 만으로 생성합니다.

npm install @altscodex/sdk    # Node 18+

const AltsCodexBackend = require('@altscodex/sdk/backend');

// 리소스 서버(당신의 앱) — 로그인 자격증명 없이 authServerUrl 만으로 생성 (v4)
const rs = new AltsCodexBackend({
  authServerUrl: 'https://api.altscodex.com',
  // introspect(RFC 7662) 를 쓸 때만 필요 — 서버-투-서버 내부 토큰
  internalToken: process.env.INTERNAL_TOKEN,
});

Verify verifyAgentToken — verify, gate scope, act verifyAgentToken — 검증 · 스코프 게이트 · 수행

await rs.verifyAgentToken(jwt, { audience, clockToleranceSec? }) — Fetches & caches the D-Server JWKS (${authServerUrl}/.well-known/jwks.json; a kid miss triggers one forced refresh to absorb key rotation), verifies the ES256 signature, checks exp (and nbf if present), and matches aud. Then it parses the delegation claims and returns them. D서버 JWKS(${authServerUrl}/.well-known/jwks.json)를 조회·캐시하고(kid 미스 시 1회 강제 갱신으로 키 로테이션 흡수), ES256 서명을 검증하고, exp(있으면 nbf 도)를 확인하고, aud 를 대조합니다. 이후 위임 클레임을 파싱해 반환합니다.

Returned AgentVerification: 반환값 AgentVerification:

Full Express example — verify, gate on scope, double-check high-risk actions, then apply RAR limits: 전체 Express 예시 — 검증 → 스코프 게이트 → 고위험 이중검증 → RAR 한도 적용:

const express = require('express');
const AltsCodexBackend = require('@altscodex/sdk/backend');

const app = express();
app.use(express.json());

const rs = new AltsCodexBackend({
  authServerUrl: process.env.ALTSCODEX_AUTH_SERVER_URL, // https://api.altscodex.com
  internalToken: process.env.INTERNAL_TOKEN,            // introspect 용
});

const AUDIENCE = 'app_marketplace'; // 이 앱의 등록 식별자 (토큰 aud 와 대조)

app.post('/market/bid', async (req, res) => {
  // 1) Bearer 토큰 추출
  const header = req.headers.authorization || '';
  const token = header.startsWith('Bearer ') ? header.slice(7) : null;
  if (!token) return res.status(401).json({ error: 'missing_token' });

  // 2) 오프라인 검증 — 서명 · aud · exp 확인 후 위임 클레임 파싱
  let v;
  try {
    v = await rs.verifyAgentToken(token, { audience: AUDIENCE });
  } catch (err) {
    // err.reason: invalid_signature / audience_mismatch / token_expired ...
    return res.status(401).json({ error: err.reason || 'invalid_token' });
  }

  // 3) 스코프 게이트 — 위임 범위 밖이면 거부
  if (!v.scope.split(' ').includes('market:bid')) {
    return res.status(403).json({ error: 'insufficient_scope' });
  }

  // 4) 고위험(입찰/송금) 직전 introspect 로 실시간 활성 재확인 — 철회 즉시 반영
  //    verifyAgentToken 은 오프라인이라 발급 후의 철회를 볼 수 없다.
  const info = await rs.introspect(token);
  if (!info.active) return res.status(403).json({ error: 'delegation_revoked' });

  // 5) RAR 한도 안에서만 수행 — 위임이 준 max_bid 상한과 카테고리를 읽는다
  const rule = v.details.find((d) => d.type === 'altscodex:market_bid');
  const maxBid = rule && rule.limits ? rule.limits.max_bid : undefined;
  const categories = rule ? rule.categories : undefined;
  if (req.body.amount > Number(maxBid)) {
    return res.status(403).json({ error: 'bid_over_limit', maxBid });
  }

  // ... maxBid 이하로 입찰 수행 ...
  res.json({ ok: true, user: v.user, agent: v.agent && v.agent.sub, maxBid, categories });
});

app.listen(3070, () => console.log('resource server on 3070'));

Errors Failure reasons (err.reason) 실패 사유 (err.reason)

On failure verifyAgentToken throws an Error whose .reason is one of the codes below. Map them to HTTP status as shown. 실패 시 verifyAgentToken 은 아래 코드 중 하나를 .reason 에 담아 Error 를 던집니다. 표시된 HTTP 상태로 매핑하세요.

A valid but under-scoped token is not a verification error — verifyAgentToken succeeds and you enforce scope yourself (return 403 when the required scope is absent). 유효하지만 스코프가 모자란 토큰은 검증 오류가 아닙니다 — verifyAgentToken 은 성공하며, 스코프 확인은 앱이 직접 합니다(필요 스코프가 없으면 403 반환).

Path Which path: MCP vs REST 권장 경로: MCP vs REST

MCP server (recommended) — expose your capabilities through the AltsCodex MCP server; token verification and scope gating happen at the MCP layer, so your app rarely touches raw JWTs. REST + verifyAgentToken (compatible) — an existing REST app verifies delegated tokens directly with this SDK, exactly as shown above. MCP 서버(권장) — 기능을 AltsCodex MCP 서버로 노출하면 토큰 검증·스코프 게이트가 MCP 레이어에서 처리되어 앱이 원시 JWT 를 거의 다루지 않습니다. REST + verifyAgentToken(호환) — 기존 REST 앱은 위 예시처럼 이 SDK 로 위임 토큰을 직접 검증합니다.

Vocab Scope & RAR vocabulary (v1) 스코프 & RAR 어휘 (v1)

The scope string and details (RAR) you read from a verified token come from this fixed vocabulary. Canonical source: SCOPES.md in the delegation server (if this doc and the code constant differ, the code wins). 검증된 토큰에서 읽는 scope 문자열과 details(RAR)는 아래 고정 어휘에서 옵니다. 정본은 위임 서버의 SCOPES.md 입니다(이 문서와 코드 상수가 다르면 코드가 정본).

Scopes — 10 total (resource:action) 스코프 — 10종 (리소스:행위)

High-risk scopes (wallet:transfer, market:bid) are not enough on their own — they are further constrained by the RAR types below (amount / counterparty / quantity caps). 고위험 스코프(wallet:transfer, market:bid)는 그 자체만으로 부족하며, 아래 RAR 타입으로 금액·상대·수량 상한을 함께 제약합니다.

RAR authorization_details types — 3 total (RFC 9396) RAR authorization_details 타입 — 3종 (RFC 9396)

{ "type": "altscodex:market_bid", "actions": ["bid"],
  "limits": { "max_bid": "30000" }, "categories": ["game_alt"] }

Amounts are strings (parse to number before comparing). Attenuation is monotonic — the token you receive is always a subset of the delegation: the D-Server rejects a token exchange that widens scope or raises a limit, so an over-scoped request never reaches your app. 금액은 문자열입니다(비교 전 숫자 파싱). 감쇠는 단조적입니다 — 받는 토큰은 항상 위임의 부분집합입니다. 스코프를 넓히거나 한도를 올리는 토큰 교환은 D서버가 거부하므로, 범위 밖 요청은 앱에 도달조차 하지 않습니다.