@apoa/core 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +92 -0
- package/package.json +18 -3
package/README.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# @apoa/core
|
|
2
|
+
|
|
3
|
+
Reference TypeScript SDK for the [Agentic Power of Attorney (APOA)](https://github.com/agenticpoa/apoa) standard -- authorization infrastructure for AI agents.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @apoa/core
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { createToken, checkScope, generateKeyPair, createClient } from '@apoa/core';
|
|
15
|
+
|
|
16
|
+
// Generate keys and create a client
|
|
17
|
+
const keys = await generateKeyPair();
|
|
18
|
+
const client = createClient({ defaultSigningOptions: { privateKey: keys.privateKey } });
|
|
19
|
+
|
|
20
|
+
// Create a signed authorization token
|
|
21
|
+
const token = await client.createToken({
|
|
22
|
+
principal: { id: "did:apoa:you" },
|
|
23
|
+
agent: { id: "did:apoa:your-agent", name: "HomeBot Pro" },
|
|
24
|
+
services: [{
|
|
25
|
+
service: "nationwidemortgage.com",
|
|
26
|
+
scopes: ["rate_lock:read", "documents:read"],
|
|
27
|
+
constraints: { signing: false },
|
|
28
|
+
accessMode: "browser",
|
|
29
|
+
browserConfig: {
|
|
30
|
+
allowedUrls: ["https://portal.nationwidemortgage.com/*"],
|
|
31
|
+
credentialVaultRef: "1password://vault/mortgage-portal",
|
|
32
|
+
},
|
|
33
|
+
}],
|
|
34
|
+
rules: [{ id: "no-signing", description: "Never sign anything", enforcement: "hard" }],
|
|
35
|
+
expires: "2026-09-01",
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
// Authorize actions
|
|
39
|
+
const result = await client.authorize(token, "nationwidemortgage.com", "rate_lock:read");
|
|
40
|
+
// { authorized: true, checks: { revoked: false, scopeAllowed: true, ... } }
|
|
41
|
+
|
|
42
|
+
const denied = await client.authorize(token, "nationwidemortgage.com", "documents:sign");
|
|
43
|
+
// { authorized: false, reason: "scope 'documents:sign' not in authorized scopes" }
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Features
|
|
47
|
+
|
|
48
|
+
- **Token lifecycle**: create, sign (Ed25519/ES256), validate, parse
|
|
49
|
+
- **Scope matching**: hierarchical patterns (`appointments:*` matches `appointments:read`)
|
|
50
|
+
- **Constraint enforcement**: boolean denial checks
|
|
51
|
+
- **Authorization**: revocation + scope + constraints + hard/soft rules in one call
|
|
52
|
+
- **Delegation chains**: capability attenuation (permissions only narrow, never expand)
|
|
53
|
+
- **Cascade revocation**: revoke parent, all children die instantly
|
|
54
|
+
- **Audit trail**: append-only action log per token
|
|
55
|
+
- **Browser mode**: credential vault injection config (the AI never sees passwords)
|
|
56
|
+
- **263 tests** across 17 test files
|
|
57
|
+
|
|
58
|
+
## Two Usage Styles
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
// Style 1: Client instance (recommended for apps)
|
|
62
|
+
const client = createClient({
|
|
63
|
+
revocationStore: new MemoryRevocationStore(),
|
|
64
|
+
auditStore: new MemoryAuditStore(),
|
|
65
|
+
defaultSigningOptions: { privateKey: keys.privateKey },
|
|
66
|
+
});
|
|
67
|
+
await client.authorize(token, "service.com", "action:read");
|
|
68
|
+
|
|
69
|
+
// Style 2: Standalone imports (for scripts and tests)
|
|
70
|
+
import { checkScope, authorize, createToken } from '@apoa/core';
|
|
71
|
+
checkScope(token, "service.com", "action:read");
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Cross-SDK Compatibility
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
## Ecosystem
|
|
79
|
+
|
|
80
|
+
- [`@apoa/mcp`](https://www.npmjs.com/package/@apoa/mcp) -- APOA authorization for MCP servers
|
|
81
|
+
- [`@apoa/a2a`](https://github.com/agenticpoa/apoa-a2a) -- APOA authorization for A2A agent-to-agent communication
|
|
82
|
+
- [`apoa`](https://pypi.org/project/apoa/) -- Python SDK
|
|
83
|
+
|
|
84
|
+
## Links
|
|
85
|
+
|
|
86
|
+
- [Spec](https://github.com/agenticpoa/apoa/blob/main/SPEC.md)
|
|
87
|
+
- [Source](https://github.com/agenticpoa/apoa/tree/main/sdk)
|
|
88
|
+
- [Examples](https://github.com/agenticpoa/apoa/tree/main/sdk/examples)
|
|
89
|
+
|
|
90
|
+
## License
|
|
91
|
+
|
|
92
|
+
Apache-2.0
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@apoa/core",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "The reference implementation for the Agentic Power of Attorney standard",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.cjs",
|
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
}
|
|
20
20
|
},
|
|
21
21
|
"files": [
|
|
22
|
-
"dist"
|
|
22
|
+
"dist",
|
|
23
|
+
"README.md"
|
|
23
24
|
],
|
|
24
25
|
"scripts": {
|
|
25
26
|
"build": "tsup",
|
|
@@ -33,8 +34,22 @@
|
|
|
33
34
|
"authorization",
|
|
34
35
|
"agent",
|
|
35
36
|
"power-of-attorney",
|
|
36
|
-
"delegation"
|
|
37
|
+
"delegation",
|
|
38
|
+
"jwt",
|
|
39
|
+
"security",
|
|
40
|
+
"ai-agents",
|
|
41
|
+
"audit-trail",
|
|
42
|
+
"revocation"
|
|
37
43
|
],
|
|
44
|
+
"repository": {
|
|
45
|
+
"type": "git",
|
|
46
|
+
"url": "https://github.com/agenticpoa/apoa.git",
|
|
47
|
+
"directory": "sdk"
|
|
48
|
+
},
|
|
49
|
+
"homepage": "https://github.com/agenticpoa/apoa",
|
|
50
|
+
"bugs": {
|
|
51
|
+
"url": "https://github.com/agenticpoa/apoa/issues"
|
|
52
|
+
},
|
|
38
53
|
"license": "Apache-2.0",
|
|
39
54
|
"engines": {
|
|
40
55
|
"node": ">=18"
|