{"_id":"@agentlair/flue","name":"@agentlair/flue","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentlair/flue","version":"0.1.0","description":"AgentLair integration for Flue — agent identity (AATs), behavioral trust scoring, and trust-gated MCP connections.","keywords":["agentlair","flue","flueframework","ai-agent","trust","identity","eddsa","jwt","jwks","agent-security","behavioral-trust","mcp"],"homepage":"https://agentlair.dev","repository":{"type":"git","url":"git+https://github.com/piiiico/agentlair.git"},"license":"MIT","author":{"name":"AgentLair"},"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"},"./verify":{"import":"./dist/verify.js","types":"./dist/verify.d.ts"},"./mcp":{"import":"./dist/mcp.js","types":"./dist/mcp.d.ts"}},"scripts":{"build":"tsup","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"peerDependencies":{"@flue/sdk":">=0.1.0"},"peerDependenciesMeta":{"@flue/sdk":{"optional":false}},"dependencies":{"jose":"^5.0.0"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.0.0","typescript":"^5.9.3"},"engines":{"node":">=18.0.0"},"_id":"@agentlair/flue@0.1.0","gitHead":"94d118d1e1a9c6ec48141ff4e257675e7c7608fe","bugs":{"url":"https://github.com/piiiico/agentlair/issues"},"_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-JWVM5BFTkg6HMNC93Y2XRBEFS6KdJjfeBnIbMxxH/c1RB4im/0sTFCJkiNPNy+a2CbW2kyTeD6SiFTvqHQ6G+w==","shasum":"eff4ad6231fa8678f82123ddadc0ac8d0f16b210","tarball":"https://registry.npmjs.org/@agentlair/flue/-/flue-0.1.0.tgz","fileCount":12,"unpackedSize":68501,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIC2nK4ttBBtskAd95McCQEFhdKfhP4wRLLtSJNhrLK/DAiEAx8sNP7xuUAFck6I4oN94L52uq5iJD+TH3ulCu7S8gEs="}]},"_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/flue_0.1.0_1777756566228_0.028646217013789332"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-02T21:16:06.132Z","0.1.0":"2026-05-02T21:16:06.368Z","modified":"2026-05-02T21:16:06.600Z"},"maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"description":"AgentLair integration for Flue — agent identity (AATs), behavioral trust scoring, and trust-gated MCP connections.","homepage":"https://agentlair.dev","keywords":["agentlair","flue","flueframework","ai-agent","trust","identity","eddsa","jwt","jwks","agent-security","behavioral-trust","mcp"],"repository":{"type":"git","url":"git+https://github.com/piiiico/agentlair.git"},"author":{"name":"AgentLair"},"bugs":{"url":"https://github.com/piiiico/agentlair/issues"},"license":"MIT","readme":"# @agentlair/flue\n\nAgentLair integration for [Flue](https://flueframework.com) — agent identity, JWKS-verified authentication, and trust-gated MCP connections.\n\nFlue ships with no identity or auth layer by design. AgentLair fills that gap: each agent session gets a cryptographically signed identity token (AAT), verifiable by any service that accepts JWKS-backed Ed25519 JWTs — no shared secrets, no trust negotiation.\n\n## Install\n\n```bash\nnpm install @agentlair/flue\n# peer dependency\nnpm install @flue/sdk\n```\n\n## Quick Start\n\nWrap your agent handler with `withAgentLair`. Your handler receives `aal` — a live token plus decoded claims — ready to attach to any outbound call.\n\n```typescript\n// .flue/agents/my-agent.ts\nimport { withAgentLair, mcpOptions } from '@agentlair/flue';\nimport type { FlueContext } from '@agentlair/flue';\n\nexport const triggers = { webhook: true };\n\nexport default withAgentLair(\n  async ({ init, payload, env, aal }) => {\n    const agent = await init({ model: 'anthropic/claude-sonnet-4-6' });\n\n    // Attach AAT to any outbound MCP server call\n    const partnerTools = await connectMcpServer(\n      'partner',\n      mcpOptions('https://api.partner.com/mcp', aal),\n    );\n\n    const session = await agent.session();\n    return await session.prompt(payload.message as string, {\n      tools: [partnerTools],\n    });\n  },\n  {\n    audience: 'https://my-service.com',\n    scopes: ['mcp:tools:execute', 'email:send'],\n  },\n);\n```\n\nSet `AGENTLAIR_API_KEY` in your Flue environment. The wrapper reads it automatically.\n\n## Three Patterns\n\n### 1. Outbound identity — your agent calls external services\n\nUse `withAgentLair` to get a token at session start, then attach it to MCP servers, webhooks, or any HTTP call.\n\n```typescript\nimport { withAgentLair, mcpOptions } from '@agentlair/flue';\n\nexport default withAgentLair(\n  async ({ init, payload, env, aal }) => {\n    // aal.token    — raw JWT\n    // aal.bearer   — \"Bearer eyJ...\" string for Authorization header\n    // aal.name     — agent display name\n    // aal.accountId — stable account ID (persists across sessions)\n    // aal.scopes   — granted scopes\n    // aal.auditUrl — link to full audit trail for this token\n\n    // MCP connection with AAT auth\n    const tools = await connectMcpServer('data-api', mcpOptions(\n      'https://data.example.com/mcp',\n      aal,\n    ));\n\n    // Direct HTTP call with AAT auth\n    const response = await fetch('https://api.example.com/data', {\n      headers: { Authorization: aal.bearer },\n    });\n\n    const agent = await init({ model: 'anthropic/claude-sonnet-4-6' });\n    const session = await agent.session();\n    return await session.prompt(payload.message as string, { tools: [tools] });\n  },\n  {\n    audience: 'https://data.example.com',\n    scopes: ['mcp:tools:execute'],\n  },\n);\n```\n\n### 2. Inbound auth — your Flue webhook verifies callers\n\nServices built on Flue can require callers to prove their identity before executing.\n\n```typescript\n// .flue/agents/my-service.ts\nimport { verifyIncomingAAT } from '@agentlair/flue';\n\nexport const triggers = { webhook: true };\n\nexport default async function ({ init, payload, env }: FlueContext) {\n  // Verify the calling agent's identity — throws if invalid\n  const caller = await verifyIncomingAAT(\n    (payload.headers as Record<string, string>)?.authorization,\n    {\n      audience: 'https://my-service.com',\n      requiredScopes: ['mcp:tools:execute'],\n    },\n  );\n\n  // caller.accountId — stable identity across sessions\n  // caller.name      — human-readable name\n  // caller.tokenRef  — unique token ID (safe to log)\n  // caller.auditUrl  — link to caller's audit trail\n  console.log(`Request from ${caller.name} (${caller.accountId})`);\n\n  const agent = await init({ model: 'anthropic/claude-sonnet-4-6' });\n  const session = await agent.session();\n  return await session.prompt(payload.message as string);\n}\n```\n\nVerification uses `https://agentlair.dev/.well-known/jwks.json` — no API key required on the receiving side.\n\n### 3. A2A trust — session.task() with identity\n\nWhen Flue's `session.task()` delegates to child agents, pass the AAT so the child can prove identity downstream.\n\n```typescript\nimport { withAgentLair } from '@agentlair/flue';\n\nexport default withAgentLair(\n  async ({ init, payload, env, aal }) => {\n    const agent = await init({ model: 'anthropic/claude-sonnet-4-6' });\n    const session = await agent.session();\n\n    // Spawn a child task — pass the AAT in the prompt context\n    const result = await session.task(\n      `Research this topic: ${payload.query}\n       Your identity token: ${aal.token}\n       Attach it as 'Authorization: Bearer <token>' when calling external APIs.`,\n    );\n\n    return result;\n  },\n  {\n    audience: 'https://my-service.com',\n    scopes: ['mcp:tools:execute', 'memory:write'],\n  },\n);\n```\n\n## Token Lifecycle\n\nAATs expire (default: 1 hour). For long-running agents, refresh before reuse:\n\n```typescript\nimport { withAgentLair, issueAAT, isAATValid } from '@agentlair/flue';\n\n// Manual refresh pattern\nexport default withAgentLair(\n  async ({ init, payload, env, aal }) => {\n    const issueOptions = {\n      apiKey: env.AGENTLAIR_API_KEY!,\n      audience: 'https://my-service.com',\n    };\n\n    // Refresh if within 60 seconds of expiry\n    if (!isAATValid(aal, 60)) {\n      aal = await issueAAT(issueOptions);\n    }\n\n    // ... use aal\n  },\n  { audience: 'https://my-service.com' },\n);\n```\n\n## Environment Setup\n\nIn `.flue/agents/<your-agent>.ts`, AgentLair credentials come in via `env`:\n\n```typescript\n// .flue/commands.ts (if using defineCommand pattern)\nexport const agentlair = defineCommand('agentlair-cli', {\n  env: {\n    AGENTLAIR_API_KEY: process.env.AGENTLAIR_API_KEY,\n  },\n});\n```\n\nOr set `AGENTLAIR_API_KEY` in your deployment environment (Cloudflare secrets, GitHub Actions secrets, etc.).\n\n## What's an AAT?\n\nAn Agent Authentication Token is an EdDSA-signed JWT issued by AgentLair:\n\n```\n{\n  \"iss\": \"https://agentlair.dev\",\n  \"sub\": \"acc_7kLmNpQr2sT4\",          // stable agent identity\n  \"aud\": \"https://my-service.com\",\n  \"exp\": 1716000000,\n  \"jti\": \"aat_X9bYzWvU8pQr3mNk\",      // unique token ID (safe to log)\n  \"al_name\": \"my-flue-agent\",\n  \"al_email\": \"my-flue-agent@agentlair.dev\",\n  \"al_scopes\": [\"mcp:tools:execute\", \"email:send\"],\n  \"al_audit_url\": \"https://agentlair.dev/v1/audit/aat_X9bYzWvU8pQr3mNk\"\n}\n```\n\nAny service can verify it offline using `https://agentlair.dev/.well-known/jwks.json`.\n\n**Never log the raw token.** Log `jti` instead — it uniquely identifies this issuance in the audit trail.\n\n## Get an API Key\n\nRegister at [agentlair.dev](https://agentlair.dev):\n\n```bash\ncurl -X POST https://agentlair.dev/v1/register \\\n  -H 'Content-Type: application/json' \\\n  -d '{ \"name\": \"my-flue-agent\", \"recovery_email\": \"you@example.com\" }'\n```\n\nReturns `{ api_key, account_id, email_address }` — your agent's permanent identity.\n\n## Related Packages\n\n- [`@agentlair/sdk`](https://npmjs.com/package/@agentlair/sdk) — Full AgentLair client (email, vault, SCITT, sessions)\n- [`@agentlair/verify`](https://npmjs.com/package/@agentlair/verify) — Lightweight AAT verification only\n- [`@agentlair/mastra`](https://npmjs.com/package/@agentlair/mastra) — Mastra framework integration\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-f4c253313db75f50e45889b45edc71a7"}