@apoa/core 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,92 @@
+# @apoa/core
+
+Reference TypeScript SDK for the [Agentic Power of Attorney (APOA)](https://github.com/agenticpoa/apoa) standard -- authorization infrastructure for AI agents.
+
+## Install
+
+```bash
+npm install @apoa/core
+```
+
+## Quick Start
+
+```typescript
+import { createToken, checkScope, generateKeyPair, createClient } from '@apoa/core';
+
+// Generate keys and create a client
+const keys = await generateKeyPair();
+const client = createClient({ defaultSigningOptions: { privateKey: keys.privateKey } });
+
+// Create a signed authorization token
+const token = await client.createToken({
+  principal: { id: "did:apoa:you" },
+  agent: { id: "did:apoa:your-agent", name: "HomeBot Pro" },
+  services: [{
+    service: "nationwidemortgage.com",
+    scopes: ["rate_lock:read", "documents:read"],
+    constraints: { signing: false },
+    accessMode: "browser",
+    browserConfig: {
+      allowedUrls: ["https://portal.nationwidemortgage.com/*"],
+      credentialVaultRef: "1password://vault/mortgage-portal",
+    },
+  }],
+  rules: [{ id: "no-signing", description: "Never sign anything", enforcement: "hard" }],
+  expires: "2026-09-01",
+});
+
+// Authorize actions
+const result = await client.authorize(token, "nationwidemortgage.com", "rate_lock:read");
+// { authorized: true, checks: { revoked: false, scopeAllowed: true, ... } }
+
+const denied = await client.authorize(token, "nationwidemortgage.com", "documents:sign");
+// { authorized: false, reason: "scope 'documents:sign' not in authorized scopes" }
+```
+
+## Features
+
+- **Token lifecycle**: create, sign (Ed25519/ES256), validate, parse
+- **Scope matching**: hierarchical patterns (`appointments:*` matches `appointments:read`)
+- **Constraint enforcement**: boolean denial checks
+- **Authorization**: revocation + scope + constraints + hard/soft rules in one call
+- **Delegation chains**: capability attenuation (permissions only narrow, never expand)
+- **Cascade revocation**: revoke parent, all children die instantly
+- **Audit trail**: append-only action log per token
+- **Browser mode**: credential vault injection config (the AI never sees passwords)
+- **Comprehensive test suite** with cross-SDK fixture verification against the [Python SDK](https://pypi.org/project/apoa/)
+
+## Two Usage Styles
+
+```typescript
+// Style 1: Client instance (recommended for apps)
+const client = createClient({
+  revocationStore: new MemoryRevocationStore(),
+  auditStore: new MemoryAuditStore(),
+  defaultSigningOptions: { privateKey: keys.privateKey },
+});
+await client.authorize(token, "service.com", "action:read");
+
+// Style 2: Standalone imports (for scripts and tests)
+import { checkScope, authorize, createToken } from '@apoa/core';
+checkScope(token, "service.com", "action:read");
+```
+
+## Cross-SDK Compatibility
+
+Tokens created by `@apoa/core` validate in the [Python SDK](https://pypi.org/project/apoa/) and vice versa. The camelCase JWT payload round-trips correctly across both SDKs.
+
+## Ecosystem
+
+- [`@apoa/mcp`](https://www.npmjs.com/package/@apoa/mcp) -- APOA authorization for MCP servers
+- [`@apoa/a2a`](https://github.com/agenticpoa/apoa-a2a) -- APOA authorization for A2A agent-to-agent communication
+- [`apoa`](https://pypi.org/project/apoa/) -- Python SDK
+
+## Links
+
+- [Spec](https://github.com/agenticpoa/apoa/blob/main/SPEC.md)
+- [Source](https://github.com/agenticpoa/apoa/tree/main/sdks/typescript)
+- [Examples](https://github.com/agenticpoa/apoa/tree/main/sdks/typescript/examples)
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -42,10 +42,12 @@ __export(index_exports, {
   ScopeViolationError: () => ScopeViolationError,
   TokenExpiredError: () => TokenExpiredError,
   authorize: () => authorize,
+  buildJWKS: () => buildJWKS,
   cascadeRevoke: () => cascadeRevoke,
   checkConstraint: () => checkConstraint,
   checkScope: () => checkScope,
   createClient: () => createClient,
+  createJWKSResolver: () => createJWKSResolver,
   createToken: () => createToken,
   decodeHeader: () => decodeHeader,
   delegate: () => delegate,
@@ -59,6 +61,7 @@ __export(index_exports, {
   matchScope: () => matchScope,
   parseDefinition: () => parseDefinition,
   parseScope: () => parseScope,
+  publicKeyToJWK: () => publicKeyToJWK,
   revoke: () => revoke,
   sign: () => sign,
   signToken: () => signToken,
@@ -208,12 +211,14 @@ function parseScope(scope) {
   return scope.split(":");
 }
 function matchScope(pattern, requested) {
+  if (!pattern || !requested) return false;
   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;
     if (patternParts[i] !== requestedParts[i]) return false;
   }
   return true;
@@ -379,8 +384,8 @@ async function authorize(token, service, action, options) {
     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())) {
+        const actionSegments = action.toLowerCase().split(":");
+        if (actionSegments.includes(ruleKey.toLowerCase())) {
           return {
             authorized: false,
             reason: `hard rule '${rule.id}' violated`,
@@ -488,6 +493,13 @@ function validateDefinition(raw) {
       }
       if (!svc.scopes || !Array.isArray(svc.scopes) || svc.scopes.length === 0) {
         errors.push(`services[${i}].scopes must be a non-empty array`);
+      } else {
+        for (let j = 0; j < svc.scopes.length; j++) {
+          const s = svc.scopes[j];
+          if (typeof s !== "string" || s.length === 0) {
+            errors.push(`services[${i}].scopes[${j}] must be a non-empty string`);
+          }
+        }
       }
       validateServiceAccessMode(svc, i, errors, warnings);
     }
@@ -538,6 +550,11 @@ function validateMetadata(metadata, errors) {
   }
   const record = metadata;
   for (const key of keys) {
+    if (key.startsWith("_")) {
+      errors.push(
+        `metadata key '${key}' uses reserved prefix '_' (reserved for SDK internal use)`
+      );
+    }
     const value = record[key];
     if (value !== null && typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
       errors.push(
@@ -614,9 +631,7 @@ function validateLegalFramework(legal, errors) {
 }
 
 // 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(),
@@ -624,19 +639,18 @@ async function revoke(tokenId, options, store) {
     reason: options.reason,
     cascaded: []
   };
-  await s.add(record);
+  await store.add(record);
   return record;
 }
 async function isRevoked(tokenId, store) {
-  const s = store ?? defaultStore;
-  const record = await s.check(tokenId);
+  const record = await store.check(tokenId);
   return record !== null;
 }
 
 // src/audit/log.ts
-var defaultStore2 = new MemoryAuditStore();
+var defaultStore = new MemoryAuditStore();
 async function logAction(tokenId, entry, store) {
-  const s = store ?? defaultStore2;
+  const s = store ?? defaultStore;
   const fullEntry = {
     ...entry,
     tokenId,
@@ -646,13 +660,13 @@ async function logAction(tokenId, entry, store) {
 }
 
 // src/audit/trail.ts
-var defaultStore3 = new MemoryAuditStore();
+var defaultStore2 = new MemoryAuditStore();
 async function getAuditTrail(tokenId, options, store) {
-  const s = store ?? defaultStore3;
+  const s = store ?? defaultStore2;
   return s.query(tokenId, options);
 }
 async function getAuditTrailByService(service, options, store) {
-  const s = store ?? defaultStore3;
+  const s = store ?? defaultStore2;
   return s.queryByService(service, options);
 }
 
@@ -682,7 +696,7 @@ async function verifySignature(token, key) {
 }
 
 // src/token/create.ts
-async function createToken(definition, options) {
+async function createToken(definition, options, parentTokenId) {
   if (definition.metadata) {
     validateMetadata2(definition.metadata);
   }
@@ -698,7 +712,10 @@ async function createToken(definition, options) {
     exp: Math.floor(
       (typeof definition.expires === "string" ? new Date(definition.expires) : definition.expires).getTime() / 1e3
     ),
-    definition: serializeDefinition(definition)
+    definition: {
+      ...serializeDefinition(definition),
+      ...parentTokenId ? { parentToken: parentTokenId } : {}
+    }
   };
   if (definition.notBefore) {
     payload.nbf = Math.floor(
@@ -719,6 +736,7 @@ async function createToken(definition, options) {
     signature: raw.split(".")[2],
     issuer,
     audience,
+    parentToken: parentTokenId,
     raw
   };
   return token;
@@ -806,13 +824,29 @@ async function validateToken(token, options) {
       "No key provided: supply publicKey, keyResolver, or publicKeyResolver"
     );
   }
+  const permittedAlgorithms = options.algorithms ?? ["EdDSA", "ES256"];
+  let headerAlg;
+  try {
+    const header = decodeHeader(rawJwt);
+    headerAlg = typeof header.alg === "string" ? header.alg : void 0;
+  } catch {
+  }
+  if (headerAlg && !permittedAlgorithms.includes(headerAlg)) {
+    errors.push(
+      `Token alg '${headerAlg}' is not in the permitted list [${permittedAlgorithms.join(", ")}]`
+    );
+  }
   let payload;
-  if (publicKey) {
+  let signatureVerified = false;
+  if (publicKey && headerAlg && permittedAlgorithms.includes(headerAlg)) {
     try {
       payload = await verifySignature(rawJwt, publicKey);
+      signatureVerified = true;
     } catch {
       errors.push("Signature verification failed");
     }
+  } else if (publicKey && !headerAlg) {
+    errors.push("Token header missing alg");
   }
   if (!payload) {
     try {
@@ -828,10 +862,12 @@ async function validateToken(token, options) {
   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");
+  if (signatureVerified) {
+    try {
+      parsedToken = payloadToToken(payload, rawJwt);
+    } catch {
+      errors.push("Token payload has invalid structure");
+    }
   }
   const clockSkew = options.clockSkew;
   if (payload.exp !== void 0) {
@@ -895,9 +931,7 @@ function base64urlDecode(input) {
 }
 
 // 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 = {
@@ -907,7 +941,7 @@ async function cascadeRevoke(parentTokenId, childTokenIds, options, store) {
       reason: options.reason ? `Cascade: ${options.reason}` : `Cascade revocation from parent ${parentTokenId}`,
       cascaded: []
     };
-    await s.add(childRecord);
+    await store.add(childRecord);
   }
   const parentRecord = {
     tokenId: parentTokenId,
@@ -916,7 +950,7 @@ async function cascadeRevoke(parentTokenId, childTokenIds, options, store) {
     reason: options.reason,
     cascaded: childTokenIds
   };
-  await s.add(parentRecord);
+  await store.add(parentRecord);
   return parentRecord;
 }
 
@@ -965,7 +999,12 @@ function verifyAttenuation(parent, child, currentDepth = 0) {
     verifyConstraintsNotRelaxed(parentService, childService);
   }
   if (parentDef.rules && parentDef.rules.length > 0) {
-    verifyRulesNotRemoved(parentDef.rules.map((r) => r.id), child);
+    verifyRulesNotRemoved(
+      parentDef.rules.map((r) => r.id),
+      child,
+      parentDef.services.flatMap((s) => s.scopes),
+      child.services.flatMap((s) => s.scopes)
+    );
   }
 }
 function verifyScopeSubset(parent, child) {
@@ -987,26 +1026,23 @@ function verifyConstraintsNotRelaxed(parent, child) {
   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
-          );
-        }
-      }
+      if (childValue === false) continue;
+      throw new AttenuationViolationError(
+        childValue === true ? `Child relaxes constraint '${key}' on service '${child.service}' (parent: false, child: true)` : `Child omits constraint '${key}' on service '${child.service}' (parent: false, child: undefined)`,
+        parent.scopes,
+        child.scopes
+      );
     }
   }
 }
-function verifyRulesNotRemoved(parentRuleIds, child) {
+function verifyRulesNotRemoved(parentRuleIds, child, parentScopes, childScopes) {
   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.`,
-        [],
-        []
+        parentScopes,
+        childScopes
       );
     }
   }
@@ -1015,7 +1051,6 @@ function verifyRulesNotRemoved(parentRuleIds, child) {
 // 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(
@@ -1027,12 +1062,32 @@ async function delegate(parentToken, childDef, options) {
     ...childDef.metadata,
     _delegationDepth: childDepth
   };
+  const inheritedServices = childDef.services.map((childSvc) => {
+    const parentSvc = parentDef.services.find((s) => s.service === childSvc.service);
+    if (!parentSvc?.constraints) return childSvc;
+    const inherited = {};
+    for (const [key, value] of Object.entries(parentSvc.constraints)) {
+      if (value === false) {
+        inherited[key] = false;
+      }
+    }
+    if (Object.keys(inherited).length === 0) return childSvc;
+    return {
+      ...childSvc,
+      constraints: { ...inherited, ...childSvc.constraints }
+    };
+  });
+  verifyAttenuation(
+    parentToken,
+    { ...childDef, services: inheritedServices, rules: mergedRules },
+    currentDepth
+  );
   const fullDefinition = {
     principal: parentDef.principal,
     // Inherited — cannot be overridden
     agent: childDef.agent,
     agentProvider: parentDef.agentProvider,
-    services: childDef.services,
+    services: inheritedServices,
     rules: mergedRules.length > 0 ? mergedRules : void 0,
     expires: childDef.expires ?? parentDef.expires,
     revocable: parentDef.revocable,
@@ -1041,8 +1096,7 @@ async function delegate(parentToken, childDef, options) {
     metadata: childMetadata,
     legal: parentDef.legal
   };
-  const childToken = await createToken(fullDefinition, options);
-  childToken.parentToken = parentToken.jti;
+  const childToken = await createToken(fullDefinition, options, parentToken.jti);
   return childToken;
 }
 function countDepth(token) {
@@ -1136,6 +1190,18 @@ function checkAttenuation(parent, child, index, errors) {
         );
       }
     }
+    if (parentService.constraints) {
+      for (const [key, parentValue] of Object.entries(parentService.constraints)) {
+        if (parentValue === false) {
+          const childValue = childService.constraints?.[key];
+          if (childValue !== false) {
+            errors.push(
+              `Chain link ${index}: constraint '${key}' on '${childService.service}' relaxed by child (parent: false, child: ${childValue === void 0 ? "undefined" : JSON.stringify(childValue)})`
+            );
+          }
+        }
+      }
+    }
   }
   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();
@@ -1146,6 +1212,82 @@ function checkAttenuation(parent, child, index, errors) {
   }
 }
 
+// src/jwks/index.ts
+var jose3 = __toESM(require("jose"), 1);
+async function publicKeyToJWK(publicKey, options) {
+  const exported = await jose3.exportJWK(publicKey);
+  const alg = options.alg ?? defaultAlgorithm(exported);
+  return {
+    ...exported,
+    kid: options.kid,
+    use: options.use ?? "sig",
+    alg
+  };
+}
+function buildJWKS(keys) {
+  return { keys };
+}
+function createJWKSResolver(url, options = {}) {
+  if (!options.fetch && !options.allowInsecure && !url.startsWith("https://")) {
+    throw new Error(
+      `JWKS URL must use https:// (got: ${JSON.stringify(url)}). Pass allowInsecure: true or a custom fetch for local development.`
+    );
+  }
+  const cacheMaxAgeMs = options.cacheMaxAgeMs ?? 60 * 60 * 1e3;
+  const cooldownMs = options.cooldownMs ?? 24 * 60 * 60 * 1e3;
+  const fetchImpl = options.fetch ?? fetch;
+  let cache = null;
+  let inflight = null;
+  async function fetchJWKS() {
+    const response = await fetchImpl(url, {
+      headers: { accept: "application/jwk-set+json, application/json" }
+    });
+    if (!response.ok) {
+      throw new Error(`JWKS fetch failed: ${response.status} ${response.statusText}`);
+    }
+    const body = await response.json();
+    if (!body || !Array.isArray(body.keys)) {
+      throw new Error("JWKS response did not contain a `keys` array");
+    }
+    return body;
+  }
+  async function getJWKS() {
+    const now = Date.now();
+    if (cache && now - cache.fetchedAt < cacheMaxAgeMs) {
+      return cache.jwks;
+    }
+    if (inflight) {
+      return inflight;
+    }
+    inflight = fetchJWKS().then((jwks) => {
+      cache = { fetchedAt: Date.now(), jwks };
+      return jwks;
+    }).catch((err) => {
+      if (cache && now - cache.fetchedAt < cooldownMs) {
+        return cache.jwks;
+      }
+      throw err;
+    }).finally(() => {
+      inflight = null;
+    });
+    return inflight;
+  }
+  return {
+    async resolve(kid) {
+      const jwks = await getJWKS();
+      const match = jwks.keys.find((k) => k.kid === kid);
+      if (!match) return null;
+      const key = await jose3.importJWK(match, match.alg);
+      return key;
+    }
+  };
+}
+function defaultAlgorithm(jwk) {
+  if (jwk.kty === "OKP" && jwk.crv === "Ed25519") return "EdDSA";
+  if (jwk.kty === "EC" && jwk.crv === "P-256") return "ES256";
+  return jwk.alg ?? "EdDSA";
+}
+
 // src/client.ts
 function createClient(options) {
   const revocationStore = options?.revocationStore ?? new MemoryRevocationStore();
@@ -1229,10 +1371,12 @@ function createClient(options) {
   ScopeViolationError,
   TokenExpiredError,
   authorize,
+  buildJWKS,
   cascadeRevoke,
   checkConstraint,
   checkScope,
   createClient,
+  createJWKSResolver,
   createToken,
   decodeHeader,
   delegate,
@@ -1246,6 +1390,7 @@ function createClient(options) {
   matchScope,
   parseDefinition,
   parseScope,
+  publicKeyToJWK,
   revoke,
   sign,
   signToken,