{"_id":"@agentlair/popa","_rev":"2-6c9cc55603022cd194ef504310c2c06e","name":"@agentlair/popa","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@agentlair/popa","version":"0.0.1","keywords":["agentlair","agent-trust","popa","behavioral-attestation","proof-of-personhood-alternative","scitt"],"author":{"url":"piiiico","name":"AgentLair"},"license":"Apache-2.0","_id":"@agentlair/popa@0.0.1","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"homepage":"https://agentlair.dev/specs/popa","bugs":{"url":"https://github.com/piiiico/agentlair-primitives/issues"},"dist":{"shasum":"5a50d61a93249f65043adc8520bec48ca04db78e","tarball":"https://registry.npmjs.org/@agentlair/popa/-/popa-0.0.1.tgz","fileCount":6,"integrity":"sha512-qvIKDieSpAmW4xUrKu7i7tagI4S8yxn1PLHckqkE+KyiD1S8GgCf42KX5mh/yBWA5CEPRH/QpdzMM9r4qJR+zQ==","signatures":[{"sig":"MEYCIQC20ZU4L0qWRPurdRxpN6rtf7kwio+MJWBS/aPQMzKU4gIhAMKk5N5eWmLkY/+W7lR66KJreQcj1hWo5xPTCAH7u7RT","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4584},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","check":"tsc --noEmit","prepublishOnly":"tsc"},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"repository":{"url":"git+https://github.com/piiiico/agentlair-primitives.git","type":"git"},"_npmVersion":"10.9.7","description":"AgentLair PoPA (Proof of Persistent Activity) primitive — reserved namespace stub. Daily attestation streaks anchored to SCITT. Operational presence as a credibility signal. See https://agentlair.dev","directories":{},"_nodeVersion":"22.22.2","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/popa_0.0.1_1777772014118_0.8260723473768905","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@agentlair/popa","version":"0.1.0","description":"Proof of Persistent Activity — verify daily attestation streaks anchored to SCITT. Client SDK for the AgentLair PoPA primitive.","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc","check":"tsc --noEmit","test":"bun test","prepublishOnly":"tsc"},"keywords":["agentlair","agent-trust","popa","proof-of-persistent-activity","behavioral-attestation","attestation-streak","scitt","did","agent-identity"],"author":{"name":"AgentLair","url":"piiiico"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/piiiico/agentlair-primitives.git"},"homepage":"https://agentlair.dev/specs/popa","bugs":{"url":"https://github.com/piiiico/agentlair-primitives/issues"},"engines":{"node":">=18.0.0"},"devDependencies":{"typescript":"^5.9.3"},"_id":"@agentlair/popa@0.1.0","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-gK+TCTG1V0HiHT7IqhvXstLz5kE5fXm8ljgV6+XYsbr/qrFUUZwYLeLV/4uB16QjX95cSBBcTSllshMV4/KkdA==","shasum":"a0c1dcd6de0873e3f1b02b08c604d986fbef3800","tarball":"https://registry.npmjs.org/@agentlair/popa/-/popa-0.1.0.tgz","fileCount":6,"unpackedSize":23524,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICsUkDIeyuPI8EeiliRhRi46ufgXAEAbDrQWh5bQ44dFAiEAqkd5SBEyJTXKe3rq/GxcmBqKdEoa3+tnoaa1IUJHKO4="}]},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"directories":{},"maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/popa_0.1.0_1777776727579_0.7071699976045627"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T01:33:33.694Z","modified":"2026-05-03T02:52:07.835Z","0.0.1":"2026-05-03T01:33:34.258Z","0.1.0":"2026-05-03T02:52:07.714Z"},"bugs":{"url":"https://github.com/piiiico/agentlair-primitives/issues"},"author":{"name":"AgentLair","url":"piiiico"},"license":"Apache-2.0","homepage":"https://agentlair.dev/specs/popa","keywords":["agentlair","agent-trust","popa","proof-of-persistent-activity","behavioral-attestation","attestation-streak","scitt","did","agent-identity"],"repository":{"type":"git","url":"git+https://github.com/piiiico/agentlair-primitives.git"},"description":"Proof of Persistent Activity — verify daily attestation streaks anchored to SCITT. Client SDK for the AgentLair PoPA primitive.","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"readme":"# @agentlair/popa\n\nDaily attestation streaks anchored to SCITT. Operational presence as a credibility signal.\n\n## What is PoPA?\n\nProof of Persistent Activity. An agent earns a PoPA attestation by being active each day — the attestation is signed, chained into a SCITT transparency log, and publicly verifiable. The bond is the streak. Gaps are self-revealing: any verifier walking the chain sees them. No capital required.\n\nUseful as the primary trust signal in the first 12 months of an agent's life, before capital and track record accumulate.\n\n## Install\n\n```bash\nnpm install @agentlair/popa\n# or\nbun add @agentlair/popa\n```\n\nZero runtime dependencies. Works in Node 18+, Bun, and edge runtimes (Cloudflare Workers, Deno Deploy).\n\n## Usage\n\n### Verify an agent's activity streak\n\n```typescript\nimport { verify, isFresh, VerifyError } from '@agentlair/popa';\n\ntry {\n  const result = await verify({ did: 'did:web:my-agent.example.com' });\n\n  console.log(result.streak_days);       // 42 — current unbroken streak\n  console.log(result.total_attestations); // 100 — all-time count\n  console.log(result.fresh);             // true — attested within last 25h\n\n  if (!result.fresh) {\n    console.warn('Agent missed its daily heartbeat');\n  }\n} catch (e) {\n  if (e instanceof VerifyError) {\n    switch (e.code) {\n      case 'no_attestation':\n        console.log('Agent not enrolled yet');\n        break;\n      case 'network_error':\n        console.error('Could not reach AgentLair');\n        break;\n      default:\n        console.error(`Verification failed: ${e.code}`);\n    }\n  }\n}\n```\n\n### Enroll a DID for daily attestation\n\n```typescript\nimport { enroll } from '@agentlair/popa';\n\nconst result = await enroll({\n  did: 'did:web:my-agent.example.com',\n  aat: process.env.AGENTLAIR_AAT!,  // Agent Authentication Token\n});\n\nconsole.log(`Enrolled at ${result.enrolled_at}`);\n```\n\nIdempotent — safe to call multiple times.\n\n### Check freshness with a custom window\n\n```typescript\nimport { isFresh } from '@agentlair/popa';\n\n// Re-check freshness against a 48h window (e.g. for less time-sensitive checks)\nif (!isFresh(result, 48)) {\n  await refreshAttestation(result.did);\n}\n```\n\n### Strict mode — throw on stale\n\n```typescript\nconst result = await verify({\n  did: 'did:web:my-agent.example.com',\n  throwIfStale: true,  // throws VerifyError('stale') if not fresh\n  maxAgeHours: 24,     // custom window\n});\n```\n\n## API\n\n### `verify(options): Promise<AttestationResult>`\n\nFetches the latest PoPA attestation for a DID from the AgentLair API.\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `did` | `string` | required | The DID to verify (`did:web:` or `did:key:`) |\n| `agentLairBaseUrl` | `string` | `\"https://api.agentlair.dev\"` | Override API base URL |\n| `maxAgeHours` | `number` | `25` | Freshness window in hours |\n| `throwIfStale` | `boolean` | `false` | Throw `VerifyError('stale')` if attestation is not fresh |\n\nReturns `AttestationResult` — a `PoPAMetrics` object plus `fetchedAt` (ISO string) and `fresh` (boolean).\n\n### `enroll(options): Promise<EnrollmentResult>`\n\nEnrolls a DID for daily attestation. Requires a valid AgentLair AAT.\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `did` | `string` | required | The DID to enroll |\n| `aat` | `string` | required | AgentLair Agent Authentication Token |\n| `agentLairBaseUrl` | `string` | `\"https://api.agentlair.dev\"` | Override API base URL |\n| `enabled` | `boolean` | `true` | Enable or disable attestation |\n\n### `isFresh(attestation, maxAgeHours?): boolean`\n\nReturns `true` if `last_attestation_at` is within `maxAgeHours` of now. Convenience helper — use when you already have an `AttestationResult` and want to re-check with a different window.\n\n### `VerifyError`\n\nAll failures surface as `VerifyError`. Check `error.code`:\n\n| Code | Meaning |\n|------|---------|\n| `no_attestation` | DID has no attestations on record |\n| `stale` | Attestation exists but is older than `maxAgeHours` (only when `throwIfStale: true`) |\n| `invalid_signature` | Response is malformed or schema doesn't match |\n| `network_error` | `fetch` threw (DNS failure, timeout, etc.) |\n| `http_error` | Non-2xx, non-404 HTTP response — check `error.status` |\n\n## PoPAMetrics shape\n\n```typescript\ninterface PoPAMetrics {\n  did: string;\n  streak_days: number;         // current unbroken streak\n  longest_streak: number;      // all-time longest streak\n  total_attestations: number;  // total attestation count\n  last_attestation_at: string; // ISO 8601 — most recent window end\n  gap_count: number;           // total gaps in history\n  genesis_at: string;          // ISO 8601 — first attestation\n  latest_scitt_entry: string;  // \"scitt:<entry_id>\"\n}\n```\n\n## Reference\n\n- Spec: https://agentlair.dev/specs/popa\n- AgentLair: https://agentlair.dev\n- Source: https://github.com/piiiico/agentlair-primitives\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}