@apoa/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1258 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APOAError: () => APOAError,
+  AttenuationViolationError: () => AttenuationViolationError,
+  ChainVerificationError: () => ChainVerificationError,
+  DefinitionValidationError: () => DefinitionValidationError,
+  MemoryAuditStore: () => MemoryAuditStore,
+  MemoryRevocationStore: () => MemoryRevocationStore,
+  MetadataValidationError: () => MetadataValidationError,
+  RevocationError: () => RevocationError,
+  RuleEnforcementError: () => RuleEnforcementError,
+  ScopeViolationError: () => ScopeViolationError,
+  TokenExpiredError: () => TokenExpiredError,
+  authorize: () => authorize,
+  cascadeRevoke: () => cascadeRevoke,
+  checkConstraint: () => checkConstraint,
+  checkScope: () => checkScope,
+  createClient: () => createClient,
+  createToken: () => createToken,
+  decodeHeader: () => decodeHeader,
+  delegate: () => delegate,
+  generateKeyPair: () => generateKeyPair2,
+  getAuditTrail: () => getAuditTrail,
+  getAuditTrailByService: () => getAuditTrailByService,
+  isBeforeNotBefore: () => isBeforeNotBefore,
+  isExpired: () => isExpired,
+  isRevoked: () => isRevoked,
+  logAction: () => logAction,
+  matchScope: () => matchScope,
+  parseDefinition: () => parseDefinition,
+  parseScope: () => parseScope,
+  revoke: () => revoke,
+  sign: () => sign,
+  signToken: () => signToken,
+  validateToken: () => validateToken,
+  verify: () => verify,
+  verifyAttenuation: () => verifyAttenuation,
+  verifyChain: () => verifyChain,
+  verifySignature: () => verifySignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils/errors.ts
+var APOAError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "APOAError";
+  }
+};
+var TokenExpiredError = class extends APOAError {
+  expiredAt;
+  constructor(message, expiredAt) {
+    super(message, "TOKEN_EXPIRED");
+    this.expiredAt = expiredAt;
+    this.name = "TokenExpiredError";
+  }
+};
+var ScopeViolationError = class extends APOAError {
+  requestedScope;
+  availableScopes;
+  constructor(message, requestedScope, availableScopes) {
+    super(message, "SCOPE_VIOLATION");
+    this.requestedScope = requestedScope;
+    this.availableScopes = availableScopes;
+    this.name = "ScopeViolationError";
+  }
+};
+var AttenuationViolationError = class extends APOAError {
+  parentScope;
+  requestedScope;
+  constructor(message, parentScope, requestedScope) {
+    super(message, "ATTENUATION_VIOLATION");
+    this.parentScope = parentScope;
+    this.requestedScope = requestedScope;
+    this.name = "AttenuationViolationError";
+  }
+};
+var RevocationError = class extends APOAError {
+  revokedAt;
+  revokedBy;
+  constructor(message, revokedAt, revokedBy) {
+    super(message, "TOKEN_REVOKED");
+    this.revokedAt = revokedAt;
+    this.revokedBy = revokedBy;
+    this.name = "RevocationError";
+  }
+};
+var ChainVerificationError = class extends APOAError {
+  failedAt;
+  reason;
+  constructor(message, failedAt, reason) {
+    super(message, "CHAIN_INVALID");
+    this.failedAt = failedAt;
+    this.reason = reason;
+    this.name = "ChainVerificationError";
+  }
+};
+var MetadataValidationError = class extends APOAError {
+  field;
+  constructor(message, field) {
+    super(message, "METADATA_INVALID");
+    this.field = field;
+    this.name = "MetadataValidationError";
+  }
+};
+var RuleEnforcementError = class extends APOAError {
+  ruleId;
+  enforcement = "hard";
+  constructor(message, ruleId) {
+    super(message, "RULE_VIOLATED");
+    this.ruleId = ruleId;
+    this.name = "RuleEnforcementError";
+  }
+};
+var DefinitionValidationError = class extends APOAError {
+  errors;
+  constructor(message, errors) {
+    super(message, "DEFINITION_INVALID");
+    this.errors = errors;
+    this.name = "DefinitionValidationError";
+  }
+};
+
+// src/utils/crypto.ts
+var jose = __toESM(require("jose"), 1);
+async function generateKeyPair2(algorithm = "EdDSA") {
+  const alg = algorithm === "EdDSA" ? "EdDSA" : "ES256";
+  const { publicKey, privateKey } = await jose.generateKeyPair(alg, {
+    extractable: true
+  });
+  return { publicKey, privateKey };
+}
+async function sign(payload, options) {
+  const alg = options.algorithm === "ES256" ? "ES256" : "EdDSA";
+  const header = { alg };
+  if (options.kid) {
+    header.kid = options.kid;
+  }
+  const jws = await new jose.CompactSign(
+    new TextEncoder().encode(JSON.stringify(payload))
+  ).setProtectedHeader(header).sign(options.privateKey);
+  return jws;
+}
+async function verify(token, key) {
+  const { payload } = await jose.compactVerify(token, key);
+  return JSON.parse(new TextDecoder().decode(payload));
+}
+
+// src/utils/time.ts
+var DEFAULT_CLOCK_SKEW = 30;
+var MAX_CLOCK_SKEW = 300;
+function normalizeSkew(clockSkew) {
+  if (clockSkew === void 0) return DEFAULT_CLOCK_SKEW;
+  if (clockSkew < 0) return 0;
+  return Math.min(clockSkew, MAX_CLOCK_SKEW);
+}
+function toDate(value) {
+  return value instanceof Date ? value : new Date(value);
+}
+function isExpired(expires, clockSkew, now) {
+  const expiresDate = toDate(expires);
+  const skew = normalizeSkew(clockSkew);
+  const currentTime = now ?? /* @__PURE__ */ new Date();
+  return currentTime.getTime() > expiresDate.getTime() + skew * 1e3;
+}
+function isBeforeNotBefore(notBefore, clockSkew, now) {
+  const notBeforeDate = toDate(notBefore);
+  const skew = normalizeSkew(clockSkew);
+  const currentTime = now ?? /* @__PURE__ */ new Date();
+  return currentTime.getTime() < notBeforeDate.getTime() - skew * 1e3;
+}
+
+// src/scope/patterns.ts
+function parseScope(scope) {
+  if (!scope) return [];
+  return scope.split(":");
+}
+function matchScope(pattern, requested) {
+  if (pattern === "*") return true;
+  const patternParts = parseScope(pattern);
+  const requestedParts = parseScope(requested);
+  if (patternParts.length !== requestedParts.length) return false;
+  for (let i = 0; i < patternParts.length; i++) {
+    if (patternParts[i] === "*") continue;
+    if (patternParts[i] !== requestedParts[i]) return false;
+  }
+  return true;
+}
+
+// src/revocation/store.ts
+var MemoryRevocationStore = class {
+  records = /* @__PURE__ */ new Map();
+  async add(record) {
+    this.records.set(record.tokenId, record);
+  }
+  async check(tokenId) {
+    return this.records.get(tokenId) ?? null;
+  }
+  async list(principalId) {
+    const results = [];
+    for (const record of this.records.values()) {
+      if (record.revokedBy === principalId) {
+        results.push(record);
+      }
+    }
+    return results;
+  }
+};
+
+// src/audit/store.ts
+var MemoryAuditStore = class {
+  entries = [];
+  async append(entry) {
+    this.entries.push(entry);
+  }
+  async query(tokenId, options) {
+    const results = this.entries.filter((e) => e.tokenId === tokenId);
+    return applyFilters(results, options);
+  }
+  async queryByService(service, options) {
+    const results = this.entries.filter((e) => e.service === service);
+    return applyFilters(results, options);
+  }
+};
+function applyFilters(entries, options) {
+  let results = entries;
+  if (options?.from) {
+    const from = options.from.getTime();
+    results = results.filter((e) => e.timestamp.getTime() >= from);
+  }
+  if (options?.to) {
+    const to = options.to.getTime();
+    results = results.filter((e) => e.timestamp.getTime() <= to);
+  }
+  if (options?.action) {
+    results = results.filter((e) => e.action === options.action);
+  }
+  if (options?.service) {
+    results = results.filter((e) => e.service === options.service);
+  }
+  if (options?.result) {
+    results = results.filter((e) => e.result === options.result);
+  }
+  const offset = options?.offset ?? 0;
+  const limit = options?.limit ?? 100;
+  results = results.slice(offset, offset + limit);
+  return results;
+}
+
+// src/scope/check.ts
+function checkScope(token, service, action) {
+  const serviceAuth = token.definition.services.find(
+    (s) => s.service === service
+  );
+  if (!serviceAuth) {
+    return {
+      allowed: false,
+      reason: `service '${service}' not found in token`
+    };
+  }
+  for (const scope of serviceAuth.scopes) {
+    if (matchScope(scope, action)) {
+      return {
+        allowed: true,
+        reason: `matched scope '${scope}'`,
+        matchedScope: scope
+      };
+    }
+  }
+  return {
+    allowed: false,
+    reason: `scope '${action}' not in authorized scopes`
+  };
+}
+function checkConstraint(token, service, constraint) {
+  const serviceAuth = token.definition.services.find(
+    (s) => s.service === service
+  );
+  if (!serviceAuth) {
+    return {
+      allowed: false,
+      reason: `service '${service}' not found in token`
+    };
+  }
+  if (!serviceAuth.constraints) {
+    return {
+      allowed: true,
+      reason: `no constraints defined for service '${service}'`
+    };
+  }
+  const value = serviceAuth.constraints[constraint];
+  if (value === void 0) {
+    return {
+      allowed: true,
+      reason: `constraint '${constraint}' not defined`
+    };
+  }
+  if (value === false) {
+    return {
+      allowed: false,
+      reason: `constraint '${constraint}' is set to false`,
+      constraint
+    };
+  }
+  return {
+    allowed: true,
+    reason: `constraint '${constraint}' is set to ${JSON.stringify(value)}`
+  };
+}
+async function authorize(token, service, action, options) {
+  if (options?.revocationStore) {
+    const record = await options.revocationStore.check(token.jti);
+    if (record) {
+      return {
+        authorized: false,
+        reason: "token has been revoked",
+        checks: { revoked: true }
+      };
+    }
+  }
+  const scopeResult = checkScope(token, service, action);
+  if (!scopeResult.allowed) {
+    return {
+      authorized: false,
+      reason: scopeResult.reason,
+      checks: { revoked: false, scopeAllowed: false }
+    };
+  }
+  const serviceAuth = token.definition.services.find(
+    (s) => s.service === service
+  );
+  if (serviceAuth?.constraints) {
+    const actionSegments = action.split(":");
+    for (const [key, value] of Object.entries(serviceAuth.constraints)) {
+      if (value === false && actionSegments.includes(key)) {
+        return {
+          authorized: false,
+          reason: `constraint '${key}' is set to false`,
+          checks: { revoked: false, scopeAllowed: true, constraintsPassed: false }
+        };
+      }
+    }
+  }
+  const rules = token.definition.rules;
+  const violations = [];
+  if (rules && rules.length > 0) {
+    for (const rule of rules) {
+      if (rule.enforcement === "hard") {
+        const ruleKey = rule.id.startsWith("no-") ? rule.id.slice(3) : rule.id;
+        const actionLower = action.toLowerCase();
+        if (actionLower.includes(ruleKey.toLowerCase())) {
+          return {
+            authorized: false,
+            reason: `hard rule '${rule.id}' violated`,
+            checks: {
+              revoked: false,
+              scopeAllowed: true,
+              constraintsPassed: true,
+              rulesPassed: false
+            }
+          };
+        }
+      }
+    }
+    for (const rule of rules) {
+      if (rule.enforcement === "soft") {
+        const violation = {
+          ruleId: rule.id,
+          tokenId: token.jti,
+          action,
+          service,
+          timestamp: /* @__PURE__ */ new Date(),
+          details: rule.description
+        };
+        violations.push(violation);
+        if (options?.auditStore) {
+          await options.auditStore.append({
+            tokenId: token.jti,
+            timestamp: violation.timestamp,
+            action,
+            service,
+            result: "escalated",
+            details: { ruleId: rule.id, ruleDescription: rule.description }
+          });
+        }
+        if (rule.onViolation) {
+          await rule.onViolation(violation);
+        }
+      }
+    }
+  }
+  return {
+    authorized: true,
+    checks: {
+      revoked: false,
+      scopeAllowed: true,
+      constraintsPassed: true,
+      rulesPassed: true
+    },
+    violations: violations.length > 0 ? violations : void 0
+  };
+}
+
+// src/token/parse.ts
+function parseDefinition(input, format) {
+  const detectedFormat = format ?? (input.trimStart().startsWith("{") ? "json" : "yaml");
+  let raw;
+  try {
+    if (detectedFormat === "json") {
+      raw = JSON.parse(input);
+    } else {
+      throw new Error('YAML parsing requires the "yaml" package. Use JSON format or install "yaml".');
+    }
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new DefinitionValidationError("Failed to parse definition", [
+        `Invalid ${detectedFormat}: ${err.message}`
+      ]);
+    }
+    throw err;
+  }
+  return validateDefinition(raw);
+}
+function validateDefinition(raw) {
+  const errors = [];
+  const warnings = [];
+  if (!raw || typeof raw !== "object") {
+    throw new DefinitionValidationError("Definition must be an object", [
+      "Definition must be an object"
+    ]);
+  }
+  const obj = raw;
+  if (!obj.principal || typeof obj.principal !== "object") {
+    errors.push("missing required field 'principal'");
+  } else {
+    const p = obj.principal;
+    if (!p.id || typeof p.id !== "string") {
+      errors.push("'principal.id' must be a non-empty string");
+    }
+  }
+  if (!obj.agent || typeof obj.agent !== "object") {
+    errors.push("missing required field 'agent'");
+  } else {
+    const a = obj.agent;
+    if (!a.id || typeof a.id !== "string") {
+      errors.push("'agent.id' must be a non-empty string");
+    }
+  }
+  if (!obj.services || !Array.isArray(obj.services) || obj.services.length === 0) {
+    errors.push("'services' must be a non-empty array");
+  } else {
+    for (let i = 0; i < obj.services.length; i++) {
+      const svc = obj.services[i];
+      if (!svc.service || typeof svc.service !== "string") {
+        errors.push(`services[${i}].service must be a non-empty string`);
+      }
+      if (!svc.scopes || !Array.isArray(svc.scopes) || svc.scopes.length === 0) {
+        errors.push(`services[${i}].scopes must be a non-empty array`);
+      }
+      validateServiceAccessMode(svc, i, errors, warnings);
+    }
+  }
+  if (obj.expires === void 0 || obj.expires === null) {
+    errors.push("missing required field 'expires'");
+  }
+  if (obj.metadata !== void 0) {
+    validateMetadata(obj.metadata, errors);
+  }
+  if (obj.agentProvider !== void 0) {
+    validateAgentProvider(obj.agentProvider, errors);
+  }
+  if (obj.legal !== void 0) {
+    validateLegalFramework(obj.legal, errors);
+  }
+  if (errors.length > 0) {
+    const err = new DefinitionValidationError(
+      `Invalid definition: ${errors.length} problem(s) found`,
+      errors
+    );
+    err.warnings = warnings;
+    throw err;
+  }
+  const def = obj;
+  if (typeof def.expires === "string") {
+    def.expires = def.expires;
+  }
+  if (typeof def.notBefore === "string") {
+    def.notBefore = def.notBefore;
+  }
+  return def;
+}
+function validateMetadata(metadata, errors) {
+  if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+    errors.push("'metadata' must be a plain object");
+    return;
+  }
+  const keys = Object.keys(metadata);
+  if (keys.length > 20) {
+    errors.push(`metadata has ${keys.length} keys (max 20)`);
+  }
+  const serialized = JSON.stringify(metadata);
+  if (serialized.length > 1024) {
+    errors.push(
+      `metadata serialized size is ${serialized.length} bytes (max 1024)`
+    );
+  }
+  const record = metadata;
+  for (const key of keys) {
+    const value = record[key];
+    if (value !== null && typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+      errors.push(
+        `metadata['${key}'] has invalid type '${typeof value}' (must be string | number | boolean | null)`
+      );
+    }
+  }
+}
+function validateServiceAccessMode(svc, index, errors, warnings) {
+  const accessMode = svc.accessMode;
+  if (accessMode === "browser") {
+    if (!svc.browserConfig || typeof svc.browserConfig !== "object") {
+      errors.push(
+        `services[${index}] has accessMode 'browser' but no browserConfig. Browser-based access requires explicit URL restrictions and a credential vault reference.`
+      );
+      return;
+    }
+    const bc = svc.browserConfig;
+    if (!bc.allowedUrls || !Array.isArray(bc.allowedUrls) || bc.allowedUrls.length === 0) {
+      errors.push(
+        `services[${index}].browserConfig.allowedUrls must be a non-empty array`
+      );
+    }
+    if (!bc.credentialVaultRef || typeof bc.credentialVaultRef !== "string") {
+      errors.push(
+        `services[${index}].browserConfig.credentialVaultRef must be a non-empty string`
+      );
+    }
+    if (bc.maxSessionDuration !== void 0) {
+      if (typeof bc.maxSessionDuration !== "number" || bc.maxSessionDuration > 86400) {
+        errors.push(
+          `services[${index}].browserConfig.maxSessionDuration must be <= 86400 seconds`
+        );
+      }
+    }
+  }
+  if (accessMode === "api" && svc.browserConfig) {
+    warnings.push(
+      `services[${index}] has accessMode 'api' but browserConfig is present (will be ignored)`
+    );
+  }
+}
+function validateAgentProvider(provider, errors) {
+  if (typeof provider !== "object" || provider === null) {
+    errors.push("'agentProvider' must be an object");
+    return;
+  }
+  const p = provider;
+  if (!p.name || typeof p.name !== "string") {
+    errors.push("'agentProvider.name' is required and must be a non-empty string");
+  }
+}
+function validateLegalFramework(legal, errors) {
+  if (typeof legal !== "object" || legal === null) {
+    errors.push("'legal' must be an object");
+    return;
+  }
+  const l = legal;
+  if (l.model !== "provider-as-agent") {
+    errors.push("'legal.model' must be 'provider-as-agent'");
+  }
+  if (l.jurisdiction !== void 0) {
+    if (typeof l.jurisdiction !== "string") {
+      errors.push("'legal.jurisdiction' must be a string");
+    } else {
+      const iso3166Pattern = /^[A-Z]{2}(-[A-Z0-9]{1,3})?$/;
+      if (!iso3166Pattern.test(l.jurisdiction)) {
+        errors.push(
+          `'legal.jurisdiction' must be ISO 3166 format (e.g., "US", "US-CA", "GB"), got '${l.jurisdiction}'`
+        );
+      }
+    }
+  }
+}
+
+// src/revocation/revoke.ts
+var defaultStore = new MemoryRevocationStore();
+async function revoke(tokenId, options, store) {
+  const s = store ?? defaultStore;
+  const record = {
+    tokenId,
+    revokedAt: /* @__PURE__ */ new Date(),
+    revokedBy: options.revokedBy,
+    reason: options.reason,
+    cascaded: []
+  };
+  await s.add(record);
+  return record;
+}
+async function isRevoked(tokenId, store) {
+  const s = store ?? defaultStore;
+  const record = await s.check(tokenId);
+  return record !== null;
+}
+
+// src/audit/log.ts
+var defaultStore2 = new MemoryAuditStore();
+async function logAction(tokenId, entry, store) {
+  const s = store ?? defaultStore2;
+  const fullEntry = {
+    ...entry,
+    tokenId,
+    timestamp: /* @__PURE__ */ new Date()
+  };
+  await s.append(fullEntry);
+}
+
+// src/audit/trail.ts
+var defaultStore3 = new MemoryAuditStore();
+async function getAuditTrail(tokenId, options, store) {
+  const s = store ?? defaultStore3;
+  return s.query(tokenId, options);
+}
+async function getAuditTrailByService(service, options, store) {
+  const s = store ?? defaultStore3;
+  return s.queryByService(service, options);
+}
+
+// src/token/sign.ts
+var jose2 = __toESM(require("jose"), 1);
+async function signToken(payload, options) {
+  const alg = options.algorithm === "ES256" ? "ES256" : "EdDSA";
+  const header = { alg };
+  if (options.kid) {
+    header.kid = options.kid;
+  }
+  const jws = await new jose2.CompactSign(
+    new TextEncoder().encode(JSON.stringify(payload))
+  ).setProtectedHeader(header).sign(options.privateKey);
+  return jws;
+}
+function decodeHeader(token) {
+  const [headerB64] = token.split(".");
+  if (!headerB64) throw new Error("Invalid JWS: missing header");
+  return JSON.parse(
+    new TextDecoder().decode(jose2.base64url.decode(headerB64))
+  );
+}
+async function verifySignature(token, key) {
+  const { payload } = await jose2.compactVerify(token, key);
+  return JSON.parse(new TextDecoder().decode(payload));
+}
+
+// src/token/create.ts
+async function createToken(definition, options) {
+  if (definition.metadata) {
+    validateMetadata2(definition.metadata);
+  }
+  const jti = crypto.randomUUID();
+  const issuedAt = /* @__PURE__ */ new Date();
+  const issuer = definition.principal.id;
+  const audience = definition.services.map((s) => s.service);
+  const payload = {
+    jti,
+    iss: issuer,
+    aud: audience,
+    iat: Math.floor(issuedAt.getTime() / 1e3),
+    exp: Math.floor(
+      (typeof definition.expires === "string" ? new Date(definition.expires) : definition.expires).getTime() / 1e3
+    ),
+    definition: serializeDefinition(definition)
+  };
+  if (definition.notBefore) {
+    payload.nbf = Math.floor(
+      (typeof definition.notBefore === "string" ? new Date(definition.notBefore) : definition.notBefore).getTime() / 1e3
+    );
+  }
+  const raw = await signToken(payload, options);
+  const sizeBytes = new TextEncoder().encode(raw).length;
+  if (sizeBytes > 8192) {
+    throw new MetadataValidationError(
+      `Token size is ${sizeBytes} bytes (max 8192). Issue multiple tokens for large authorization surfaces.`
+    );
+  }
+  const token = {
+    jti,
+    definition,
+    issuedAt,
+    signature: raw.split(".")[2],
+    issuer,
+    audience,
+    raw
+  };
+  return token;
+}
+function validateMetadata2(metadata) {
+  const keys = Object.keys(metadata);
+  if (keys.length > 20) {
+    throw new MetadataValidationError(
+      `Metadata has ${keys.length} keys (max 20)`
+    );
+  }
+  const serialized = JSON.stringify(metadata);
+  if (serialized.length > 1024) {
+    throw new MetadataValidationError(
+      `Metadata serialized size is ${serialized.length} bytes (max 1024)`
+    );
+  }
+  for (const key of keys) {
+    const value = metadata[key];
+    if (value !== null && typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+      throw new MetadataValidationError(
+        `Metadata key '${key}' has invalid type '${typeof value}'`,
+        key
+      );
+    }
+  }
+}
+function serializeDefinition(def) {
+  return {
+    ...def,
+    expires: def.expires instanceof Date ? def.expires.toISOString() : def.expires,
+    notBefore: def.notBefore instanceof Date ? def.notBefore.toISOString() : def.notBefore,
+    // Strip non-serializable onViolation callbacks from rules
+    rules: def.rules?.map(({ onViolation: _, ...rest }) => rest)
+  };
+}
+
+// src/token/validate.ts
+async function validateToken(token, options) {
+  const errors = [];
+  const warnings = [];
+  let parsedToken;
+  const rawJwt = typeof token === "string" ? token : token.raw;
+  let publicKey;
+  if (options.publicKey) {
+    publicKey = options.publicKey;
+  } else if (options.keyResolver) {
+    try {
+      const header = decodeHeader(rawJwt);
+      const kid = header.kid;
+      if (kid) {
+        const resolved = await options.keyResolver.resolve(kid);
+        if (resolved) {
+          publicKey = resolved;
+        } else {
+          errors.push(`Key resolver returned null for kid '${kid}'`);
+        }
+      } else {
+        errors.push("Token has no kid in header and keyResolver requires one");
+      }
+    } catch {
+      errors.push("Failed to decode token header for key resolution");
+    }
+  } else if (options.publicKeyResolver) {
+    try {
+      const header = decodeHeader(rawJwt);
+      const payloadB64 = rawJwt.split(".")[1];
+      if (payloadB64) {
+        const payloadJson = new TextDecoder().decode(
+          base64urlDecode(payloadB64)
+        );
+        const payload2 = JSON.parse(payloadJson);
+        const issuer = payload2.iss;
+        if (issuer) {
+          publicKey = await options.publicKeyResolver(issuer);
+        } else {
+          errors.push("Token has no issuer (iss) claim for publicKeyResolver");
+        }
+      }
+    } catch {
+      errors.push("Failed to decode token for issuer-based key resolution");
+    }
+  } else {
+    errors.push(
+      "No key provided: supply publicKey, keyResolver, or publicKeyResolver"
+    );
+  }
+  let payload;
+  if (publicKey) {
+    try {
+      payload = await verifySignature(rawJwt, publicKey);
+    } catch {
+      errors.push("Signature verification failed");
+    }
+  }
+  if (!payload) {
+    try {
+      const payloadB64 = rawJwt.split(".")[1];
+      if (payloadB64) {
+        payload = JSON.parse(
+          new TextDecoder().decode(base64urlDecode(payloadB64))
+        );
+      }
+    } catch {
+    }
+  }
+  if (!payload) {
+    return { valid: false, errors: errors.length > 0 ? errors : ["Unable to decode token"], warnings };
+  }
+  try {
+    parsedToken = payloadToToken(payload, rawJwt);
+  } catch {
+    errors.push("Token payload has invalid structure");
+  }
+  const clockSkew = options.clockSkew;
+  if (payload.exp !== void 0) {
+    const expiresDate = new Date(payload.exp * 1e3);
+    if (isExpired(expiresDate, clockSkew)) {
+      errors.push(`Token expired at ${expiresDate.toISOString()}`);
+    }
+  } else {
+    errors.push("Token has no expiration (exp) claim");
+  }
+  if (payload.nbf !== void 0) {
+    const notBeforeDate = new Date(payload.nbf * 1e3);
+    if (isBeforeNotBefore(notBeforeDate, clockSkew)) {
+      errors.push(`Token not valid before ${notBeforeDate.toISOString()}`);
+    }
+  }
+  const checkRevocation = options.checkRevocation !== false;
+  if (checkRevocation && options.revocationStore && payload.jti) {
+    const revRecord = await options.revocationStore.check(
+      payload.jti
+    );
+    if (revRecord) {
+      errors.push(
+        `Token has been revoked (at ${revRecord.revokedAt.toISOString()} by ${revRecord.revokedBy})`
+      );
+    }
+  }
+  const sizeBytes = new TextEncoder().encode(rawJwt).length;
+  if (sizeBytes > 4096) {
+    warnings.push(`Token size is ${sizeBytes} bytes (exceeds 4KB recommended limit)`);
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    token: parsedToken,
+    warnings: warnings.length > 0 ? warnings : void 0
+  };
+}
+function payloadToToken(payload, raw) {
+  const definition = payload.definition;
+  if (!definition) throw new Error("Missing definition in payload");
+  return {
+    jti: payload.jti,
+    definition,
+    issuedAt: new Date(payload.iat * 1e3),
+    signature: raw.split(".")[2],
+    issuer: payload.iss,
+    audience: payload.aud,
+    parentToken: definition.parentToken ?? void 0,
+    raw
+  };
+}
+function base64urlDecode(input) {
+  const padded = input + "=".repeat((4 - input.length % 4) % 4);
+  const binary = atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// src/revocation/cascade.ts
+var defaultStore4 = new MemoryRevocationStore();
+async function cascadeRevoke(parentTokenId, childTokenIds, options, store) {
+  const s = store ?? defaultStore4;
+  const revokedAt = /* @__PURE__ */ new Date();
+  for (const childId of childTokenIds) {
+    const childRecord = {
+      tokenId: childId,
+      revokedAt,
+      revokedBy: options.revokedBy,
+      reason: options.reason ? `Cascade: ${options.reason}` : `Cascade revocation from parent ${parentTokenId}`,
+      cascaded: []
+    };
+    await s.add(childRecord);
+  }
+  const parentRecord = {
+    tokenId: parentTokenId,
+    revokedAt,
+    revokedBy: options.revokedBy,
+    reason: options.reason,
+    cascaded: childTokenIds
+  };
+  await s.add(parentRecord);
+  return parentRecord;
+}
+
+// src/scope/attenuate.ts
+function verifyAttenuation(parent, child, currentDepth = 0) {
+  const parentDef = parent.definition;
+  if (parentDef.delegatable === false) {
+    throw new AttenuationViolationError(
+      "Parent token does not allow delegation",
+      parentDef.services.flatMap((s) => s.scopes),
+      child.services.flatMap((s) => s.scopes)
+    );
+  }
+  if (parentDef.maxDelegationDepth !== void 0) {
+    if (currentDepth >= parentDef.maxDelegationDepth) {
+      throw new AttenuationViolationError(
+        `Delegation depth ${currentDepth + 1} exceeds maxDelegationDepth ${parentDef.maxDelegationDepth}`,
+        parentDef.services.flatMap((s) => s.scopes),
+        child.services.flatMap((s) => s.scopes)
+      );
+    }
+  }
+  if (child.expires !== void 0) {
+    const childExp = child.expires instanceof Date ? child.expires.getTime() : new Date(child.expires).getTime();
+    const parentExp = parentDef.expires instanceof Date ? parentDef.expires.getTime() : new Date(parentDef.expires).getTime();
+    if (childExp > parentExp) {
+      throw new AttenuationViolationError(
+        "Child token expiration exceeds parent expiration",
+        parentDef.services.flatMap((s) => s.scopes),
+        child.services.flatMap((s) => s.scopes)
+      );
+    }
+  }
+  for (const childService of child.services) {
+    const parentService = parentDef.services.find(
+      (s) => s.service === childService.service
+    );
+    if (!parentService) {
+      throw new AttenuationViolationError(
+        `Child requests service '${childService.service}' not in parent token`,
+        parentDef.services.flatMap((s) => s.scopes),
+        child.services.flatMap((s) => s.scopes)
+      );
+    }
+    verifyScopeSubset(parentService, childService);
+    verifyConstraintsNotRelaxed(parentService, childService);
+  }
+  if (parentDef.rules && parentDef.rules.length > 0) {
+    verifyRulesNotRemoved(parentDef.rules.map((r) => r.id), child);
+  }
+}
+function verifyScopeSubset(parent, child) {
+  for (const childScope of child.scopes) {
+    const matched = parent.scopes.some(
+      (parentScope) => matchScope(parentScope, childScope)
+    );
+    if (!matched) {
+      throw new AttenuationViolationError(
+        `Child scope '${childScope}' on service '${child.service}' is not covered by parent scopes [${parent.scopes.join(", ")}]`,
+        parent.scopes,
+        child.scopes
+      );
+    }
+  }
+}
+function verifyConstraintsNotRelaxed(parent, child) {
+  if (!parent.constraints) return;
+  for (const [key, parentValue] of Object.entries(parent.constraints)) {
+    if (parentValue === false) {
+      const childValue = child.constraints?.[key];
+      if (childValue === true || childValue === void 0) {
+        if (childValue === true) {
+          throw new AttenuationViolationError(
+            `Child relaxes constraint '${key}' on service '${child.service}' (parent: false, child: true)`,
+            parent.scopes,
+            child.scopes
+          );
+        }
+      }
+    }
+  }
+}
+function verifyRulesNotRemoved(parentRuleIds, child) {
+  const childRuleIds = new Set(child.rules?.map((r) => r.id) ?? []);
+  for (const parentRuleId of parentRuleIds) {
+    if (!childRuleIds.has(parentRuleId)) {
+      throw new AttenuationViolationError(
+        `Child removes parent rule '${parentRuleId}'. Rules can only be added, not removed.`,
+        [],
+        []
+      );
+    }
+  }
+}
+
+// src/delegation/chain.ts
+async function delegate(parentToken, childDef, options) {
+  const currentDepth = countDepth(parentToken);
+  verifyAttenuation(parentToken, childDef, currentDepth);
+  const parentDef = parentToken.definition;
+  const parentRules = parentDef.rules ?? [];
+  const childExtraRules = (childDef.rules ?? []).filter(
+    (cr) => !parentRules.some((pr) => pr.id === cr.id)
+  );
+  const mergedRules = [...parentRules, ...childExtraRules];
+  const childDepth = currentDepth + 1;
+  const childMetadata = {
+    ...childDef.metadata,
+    _delegationDepth: childDepth
+  };
+  const fullDefinition = {
+    principal: parentDef.principal,
+    // Inherited — cannot be overridden
+    agent: childDef.agent,
+    agentProvider: parentDef.agentProvider,
+    services: childDef.services,
+    rules: mergedRules.length > 0 ? mergedRules : void 0,
+    expires: childDef.expires ?? parentDef.expires,
+    revocable: parentDef.revocable,
+    delegatable: parentDef.delegatable,
+    maxDelegationDepth: parentDef.maxDelegationDepth,
+    metadata: childMetadata,
+    legal: parentDef.legal
+  };
+  const childToken = await createToken(fullDefinition, options);
+  childToken.parentToken = parentToken.jti;
+  return childToken;
+}
+function countDepth(token) {
+  const stored = token.definition.metadata?._delegationDepth;
+  if (typeof stored === "number") return stored;
+  return token.parentToken ? 1 : 0;
+}
+
+// src/delegation/verify.ts
+async function verifyChain(chain, store) {
+  const errors = [];
+  let failedAt;
+  if (chain.length === 0) {
+    return {
+      valid: false,
+      depth: 0,
+      errors: ["Chain is empty"],
+      root: void 0,
+      leaf: void 0
+    };
+  }
+  if (chain.length === 1) {
+    const token = chain[0];
+    await checkTokenValidity(token, 0, errors, store);
+    return {
+      valid: errors.length === 0,
+      depth: 0,
+      errors,
+      failedAt: errors.length > 0 ? 0 : void 0,
+      root: token,
+      leaf: token
+    };
+  }
+  for (let i = 0; i < chain.length; i++) {
+    const token = chain[i];
+    const errorsBefore = errors.length;
+    await checkTokenValidity(token, i, errors, store);
+    if (i > 0) {
+      const parent = chain[i - 1];
+      checkAttenuation(parent, token, i, errors);
+      if (token.parentToken !== parent.jti) {
+        errors.push(
+          `Chain link ${i}: parentToken '${token.parentToken}' does not match parent jti '${parent.jti}'`
+        );
+      }
+    }
+    if (failedAt === void 0 && errors.length > errorsBefore) {
+      failedAt = i;
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    depth: chain.length - 1,
+    errors,
+    failedAt,
+    root: chain[0],
+    leaf: chain[chain.length - 1]
+  };
+}
+async function checkTokenValidity(token, index, errors, store) {
+  if (isExpired(token.definition.expires, 0)) {
+    errors.push(`Chain link ${index}: token '${token.jti}' has expired`);
+  }
+  if (store) {
+    const record = await store.check(token.jti);
+    if (record) {
+      errors.push(
+        `Chain link ${index}: token '${token.jti}' has been revoked`
+      );
+    }
+  }
+}
+function checkAttenuation(parent, child, index, errors) {
+  for (const childService of child.definition.services) {
+    const parentService = parent.definition.services.find(
+      (s) => s.service === childService.service
+    );
+    if (!parentService) {
+      errors.push(
+        `Chain link ${index}: service '${childService.service}' not in parent token`
+      );
+      continue;
+    }
+    for (const childScope of childService.scopes) {
+      const covered = parentService.scopes.some(
+        (ps) => matchScope(ps, childScope)
+      );
+      if (!covered) {
+        errors.push(
+          `Chain link ${index}: scope '${childScope}' on '${childService.service}' not covered by parent`
+        );
+      }
+    }
+  }
+  const childExp = child.definition.expires instanceof Date ? child.definition.expires.getTime() : new Date(child.definition.expires).getTime();
+  const parentExp = parent.definition.expires instanceof Date ? parent.definition.expires.getTime() : new Date(parent.definition.expires).getTime();
+  if (childExp > parentExp) {
+    errors.push(
+      `Chain link ${index}: child expiration exceeds parent expiration`
+    );
+  }
+}
+
+// src/client.ts
+function createClient(options) {
+  const revocationStore = options?.revocationStore ?? new MemoryRevocationStore();
+  const auditStore = options?.auditStore ?? new MemoryAuditStore();
+  const keyResolver = options?.keyResolver;
+  const defaultSigningOptions = options?.defaultSigningOptions;
+  function mergeSigningOptions(opts) {
+    if (!opts && !defaultSigningOptions?.privateKey) {
+      throw new Error("No signing options provided and no defaultSigningOptions.privateKey configured");
+    }
+    return {
+      ...defaultSigningOptions,
+      ...opts
+    };
+  }
+  return {
+    async createToken(definition, opts) {
+      return createToken(definition, mergeSigningOptions(opts));
+    },
+    parseDefinition(input, format) {
+      return parseDefinition(input, format);
+    },
+    async validateToken(token, opts) {
+      return validateToken(token, {
+        ...opts,
+        keyResolver: opts?.keyResolver ?? keyResolver,
+        revocationStore,
+        checkRevocation: opts?.checkRevocation ?? true
+      });
+    },
+    async generateKeyPair(algorithm) {
+      return generateKeyPair2(algorithm);
+    },
+    checkScope(token, service, action) {
+      return checkScope(token, service, action);
+    },
+    checkConstraint(token, service, constraint) {
+      return checkConstraint(token, service, constraint);
+    },
+    async authorize(token, service, action, opts) {
+      return authorize(token, service, action, {
+        ...opts,
+        revocationStore,
+        auditStore
+      });
+    },
+    async delegate(parentToken, childDef, opts) {
+      return delegate(parentToken, childDef, mergeSigningOptions(opts));
+    },
+    async verifyChain(chain) {
+      return verifyChain(chain, revocationStore);
+    },
+    async revoke(tokenId, opts) {
+      return revoke(tokenId, opts, revocationStore);
+    },
+    async isRevoked(tokenId) {
+      return isRevoked(tokenId, revocationStore);
+    },
+    async logAction(tokenId, entry) {
+      return logAction(tokenId, entry, auditStore);
+    },
+    async getAuditTrail(tokenId, opts) {
+      return getAuditTrail(tokenId, opts, auditStore);
+    },
+    async getAuditTrailByService(service, opts) {
+      return getAuditTrailByService(service, opts, auditStore);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APOAError,
+  AttenuationViolationError,
+  ChainVerificationError,
+  DefinitionValidationError,
+  MemoryAuditStore,
+  MemoryRevocationStore,
+  MetadataValidationError,
+  RevocationError,
+  RuleEnforcementError,
+  ScopeViolationError,
+  TokenExpiredError,
+  authorize,
+  cascadeRevoke,
+  checkConstraint,
+  checkScope,
+  createClient,
+  createToken,
+  decodeHeader,
+  delegate,
+  generateKeyPair,
+  getAuditTrail,
+  getAuditTrailByService,
+  isBeforeNotBefore,
+  isExpired,
+  isRevoked,
+  logAction,
+  matchScope,
+  parseDefinition,
+  parseScope,
+  revoke,
+  sign,
+  signToken,
+  validateToken,
+  verify,
+  verifyAttenuation,
+  verifyChain,
+  verifySignature
+});
+//# sourceMappingURL=index.cjs.map