@apoa/core 0.2.1 → 0.2.3

package/README.md

@@ -11,35 +11,35 @@ npm install @apoa/core
 ## Quick Start
 
 ```typescript
-import { createToken, checkScope, generateKeyPair, createClient } from '@apoa/core';
+import { APOA, generateKeyPair } from '@apoa/core';
 
-// Generate keys and create a client
 const keys = await generateKeyPair();
-const client = createClient({ defaultSigningOptions: { privateKey: keys.privateKey } });
+const apoa = new APOA({ privateKey: keys.privateKey });
 
-// Create a signed authorization token
-const token = await client.createToken({
-  principal: { id: "did:apoa:you" },
+const token = await apoa.tokens.createGrant({
+  principal: "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",
+  service: "nationwidemortgage.com",
+  scopes: ["rate_lock:read", "documents:read"],
+  constraints: { signing: false },
+  expiresIn: "30d",
 });
 
-// Authorize actions
-const result = await client.authorize(token, "nationwidemortgage.com", "rate_lock:read");
+const valid = await apoa.tokens.validate(token.raw, { publicKey: keys.publicKey });
+console.log(valid.valid); // true
+
+const result = await apoa.authorizations.check(
+  token,
+  "nationwidemortgage.com",
+  "rate_lock:read"
+);
 // { authorized: true, checks: { revoked: false, scopeAllowed: true, ... } }
 
-const denied = await client.authorize(token, "nationwidemortgage.com", "documents:sign");
+const denied = await apoa.authorizations.check(
+  token,
+  "nationwidemortgage.com",
+  "documents:sign"
+);
 // { authorized: false, reason: "scope 'documents:sign' not in authorized scopes" }
 ```
 
@@ -55,19 +55,48 @@ const denied = await client.authorize(token, "nationwidemortgage.com", "document
 - **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
+## Usage Styles
+
+### Application facade
+
+Recommended for apps. Configure keys once, then use namespaced resources.
 
 ```typescript
-// Style 1: Client instance (recommended for apps)
+import { APOA } from '@apoa/core';
+
+const apoa = new APOA({ privateKey: keys.privateKey });
+const token = await apoa.tokens.createGrant({
+  principal: "did:apoa:you",
+  agent: "did:apoa:agent",
+  service: "service.com",
+  scopes: ["action:read"],
+  expiresIn: "30d",
+});
+await apoa.authorizations.check(token, "service.com", "action:read");
+```
+
+### Protocol client
+
+Use this when you want direct access to stores, resolvers, and protocol-level options.
+
+```typescript
+import { createClient, MemoryAuditStore, MemoryRevocationStore } from '@apoa/core';
+
 const client = createClient({
   revocationStore: new MemoryRevocationStore(),
   auditStore: new MemoryAuditStore(),
   defaultSigningOptions: { privateKey: keys.privateKey },
 });
 await client.authorize(token, "service.com", "action:read");
+```
+
+### Standalone imports
 
-// Style 2: Standalone imports (for scripts and tests)
+Useful for scripts, tests, adapters, and focused protocol operations.
+
+```typescript
 import { checkScope, authorize, createToken } from '@apoa/core';
+
 checkScope(token, "service.com", "action:read");
 ```
 

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  APOA: () => APOA,
   APOAError: () => APOAError,
   AttenuationViolationError: () => AttenuationViolationError,
   ChainVerificationError: () => ChainVerificationError,
@@ -1328,7 +1329,9 @@ function createClient(options) {
   const defaultSigningOptions = options?.defaultSigningOptions;
   function mergeSigningOptions(opts) {
     if (!opts && !defaultSigningOptions?.privateKey) {
-      throw new Error("No signing options provided and no defaultSigningOptions.privateKey configured");
+      throw new Error(
+        "APOA needs a private key to create tokens. Pass `privateKey` to `new APOA({ privateKey })`, configure `createClient({ defaultSigningOptions: { privateKey } })`, or pass signing options to `createToken(...)`."
+      );
     }
     return {
       ...defaultSigningOptions,
@@ -1389,8 +1392,148 @@ function createClient(options) {
     }
   };
 }
+
+// src/apoa.ts
+var APOA = class {
+  client;
+  tokens;
+  authorizations;
+  constructor(options = {}) {
+    const { privateKey, algorithm, kid, ...clientOptions } = options;
+    this.client = createClient({
+      ...clientOptions,
+      defaultSigningOptions: privateKey ? { privateKey, algorithm, kid } : void 0
+    });
+    this.tokens = {
+      create: (definition, signingOptions) => this.client.createToken(definition, signingOptions),
+      createGrant: async (input, signingOptions) => this.client.createToken(normalizeGrantInput(input), signingOptions),
+      validate: (token, validationOptions) => this.client.validateToken(token, validationOptions),
+      parse: (input, format) => this.client.parseDefinition(input, format)
+    };
+    this.authorizations = {
+      check: (token, service, action, authorizeOptions) => this.client.authorize(token, service, action, authorizeOptions)
+    };
+  }
+  async generateKeyPair(algorithm) {
+    return this.client.generateKeyPair(algorithm);
+  }
+};
+function normalizeGrantInput(input) {
+  const errors = [];
+  if (!input || typeof input !== "object") {
+    throw invalidGrantInput(["input must be an object"]);
+  }
+  const principal = normalizePrincipal(input.principal, errors);
+  const agent = normalizeAgent(input.agent, errors);
+  const services = normalizeServices(input, errors);
+  const expires = normalizeExpires(input, errors);
+  if (errors.length > 0 || !principal || !agent || services.length === 0 || !expires) {
+    throw invalidGrantInput(errors);
+  }
+  return {
+    principal,
+    agent,
+    services,
+    expires,
+    ...input.rules ? { rules: input.rules } : {},
+    ...input.revocable !== void 0 ? { revocable: input.revocable } : {},
+    ...input.delegatable !== void 0 ? { delegatable: input.delegatable } : {},
+    ...input.maxDelegationDepth !== void 0 ? { maxDelegationDepth: input.maxDelegationDepth } : {},
+    ...input.metadata ? { metadata: input.metadata } : {},
+    ...input.agentProvider ? { agentProvider: input.agentProvider } : {},
+    ...input.legal ? { legal: input.legal } : {}
+  };
+}
+function normalizePrincipal(principal, errors) {
+  if (typeof principal === "string" && principal.trim()) {
+    return { id: principal.trim() };
+  }
+  if (principal && typeof principal === "object" && principal.id) {
+    return principal;
+  }
+  errors.push("principal is required; pass a DID string or { id }");
+  return void 0;
+}
+function normalizeAgent(agent, errors) {
+  if (typeof agent === "string" && agent.trim()) {
+    return { id: agent.trim() };
+  }
+  if (agent && typeof agent === "object" && agent.id) {
+    return agent;
+  }
+  errors.push("agent is required; pass a DID string or { id }");
+  return void 0;
+}
+function normalizeServices(input, errors) {
+  if (input.services) {
+    if (!Array.isArray(input.services) || input.services.length === 0) {
+      errors.push("services must be a non-empty array when provided");
+      return [];
+    }
+    return input.services;
+  }
+  if (!input.service) {
+    errors.push("service is required unless services is provided");
+    return [];
+  }
+  if (!input.scopes || !Array.isArray(input.scopes) || input.scopes.length === 0) {
+    errors.push("scopes must be a non-empty array unless services is provided");
+    return [];
+  }
+  return [{
+    service: input.service,
+    scopes: input.scopes,
+    ...input.constraints ? { constraints: input.constraints } : {},
+    ...input.accessMode ? { accessMode: input.accessMode } : {},
+    ...input.browserConfig ? { browserConfig: input.browserConfig } : {},
+    ...input.apiConfig ? { apiConfig: input.apiConfig } : {}
+  }];
+}
+function normalizeExpires(input, errors) {
+  if (input.expires && input.expiresIn) {
+    errors.push("pass either expires or expiresIn, not both");
+    return void 0;
+  }
+  if (input.expires) {
+    return input.expires;
+  }
+  if (input.expiresIn) {
+    return parseDurationFromNow(input.expiresIn);
+  }
+  errors.push("expires or expiresIn is required");
+  return void 0;
+}
+function parseDurationFromNow(duration) {
+  const match = /^(\d+)([smhd])$/.exec(duration);
+  if (!match) {
+    throw invalidGrantInput([
+      `expiresIn must use a clear duration like '15m', '2h', or '30d'`
+    ]);
+  }
+  const amount = Number(match[1]);
+  if (!Number.isSafeInteger(amount) || amount <= 0) {
+    throw invalidGrantInput(["expiresIn duration must be a positive integer"]);
+  }
+  const unitMs = {
+    s: 1e3,
+    m: 60 * 1e3,
+    h: 60 * 60 * 1e3,
+    d: 24 * 60 * 60 * 1e3
+  };
+  return new Date(Date.now() + amount * unitMs[match[2]]);
+}
+function invalidGrantInput(errors) {
+  return new Error(
+    [
+      "Invalid APOA grant input.",
+      ...errors.map((error) => `- ${error}`),
+      "Minimal shape: { principal, agent, service, scopes, expiresIn }"
+    ].join("\n")
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  APOA,
   APOAError,
   AttenuationViolationError,
   ChainVerificationError,