fix(addie): teach Addie that AAO supports OAuth 2.1 + OIDC#3234
Merged
Conversation
…on server Escalation #288 (Emma Mulitz / Scope3) — Addie was telling users that AAO doesn't support OAuth and that bearer tokens are the only mechanism. AAO's authorization server has been live at https://agenticadvertising.org/.well-known/oauth-authorization-server with RFC 8414 metadata, RFC 9728 protected-resource metadata for /api and /mcp, RFC 7591 dynamic client registration, and PKCE-protected authorization code flow. Addie's rules had no OAuth section, so she fabricated. Adds a Knowledge section that: - explicitly states AAO supports OAuth 2.1 + OIDC and the well-known URLs, - separates AAO platform auth (OAuth/JWT for /mcp and /api) from AdCP protocol-level bearer + optional HTTP Message Signatures between agents, - points Addie at docs/registry/index.mdx and search_docs for specifics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Applies feedback from prompt-engineer, security, ad-tech-protocol-expert, and docs-expert reviews on the original Escalation #288 fix. Knowledge rule (server/src/addie/rules/knowledge.md): - Replace "do NOT say X" negation primer with positive "common conflation" framing; lift the conflation block to the top of the section so retrieval hits it first. - Update AdCP-protocol-auth characterization to match docs/building/ integration/authentication.mdx — Bearer (3.0 baseline; read-only in 3.1+), RFC 9421 (recommended in 3.0, required for mutating ops in 3.1+), or mTLS. Previous "bearer + optional signing" was stale. - Note that OAuth ALSO appears between agents (sales agents publishing their own AS for operator-account flows) — AAO is one OAuth deployment among many, not "the" OAuth surface for AdCP. - Add bridging line: a buyer that signed into AAO via OAuth still uses a separate seller-issued bearer when calling that seller's AdCP endpoints. - Spell out facts that were missing and would misroute integrators: no client_credentials grant (use a WorkOS org API key for S2S, not /token); no RFC 8707 audience binding enforced (so one JWT covers /mcp and /api); no advertised revocation_endpoint; PKCE mandatory regardless of token_endpoint_auth_method. - Soften "no manual onboarding required" — /register is rate-limited. - Cite both repo-relative path and public URL anchor for the registry reference. - Reciprocal cross-link: append a sentence to "Audit Surfaces in AdCP" pointing back to the new section. Docs (docs/building/integration/authentication.mdx): - Close the gap docs-expert flagged: this page is the canonical "AdCP authentication" landing point but was silent on AAO platform auth. Add a short "Authenticating to AAO Platform Services" section after "Obtaining Credentials" with the well-known URLs, the no-client_credentials caveat, and a link to /docs/registry#authentication. Docs (docs/registry/index.mdx): - Add "or logging in to AAO" so search_docs queries like "AAO login" / "sign in" route to the Authentication section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ass 2) Applies second-pass feedback from prompt-engineer, security, ad-tech-protocol- expert, and docs-expert reviews on commit b621c14. Knowledge rule (server/src/addie/rules/knowledge.md): - Split the conflation block into three bullets: (1) AAO platform auth, (2) AdCP protocol auth between agents with the bridging "AAO JWT is not an AdCP credential" line elevated, (3) "Other auth surfaces" covering sales-agent operator-account OAuth and the TMP/webhook signing profiles. Item 2 was overloaded; the bridging fact was buried mid-paragraph. - Add the operator-OAuth wire signal so Addie knows when to expect it: `get_adcp_capabilities.require_operator_auth: true` or a 401 carrying `WWW-Authenticate: Bearer resource_metadata=…` (RFC 9728). - Add seller-AS issuer-pinning guidance — discovered `authorization_servers` must be pinned via adagents.json / out-of-band onboarding, not blindly trusted from the resource itself. Closes the credential-routing risk the security pass flagged. - Use specific signing terms for TMP and webhooks (Ed25519 envelope, HMAC-SHA256 per push_notification_config) so search_docs queries route. - Drop the unverifiable "~20/hr" rate-limit number on /register; the observed limit is at the edge, not application-level. - Drop the revocation_endpoint absence bullet (Addie won't recall it and stating absences invites fabrication). - Trim the audience-binding bullet to one positive sentence ("the same user JWT is accepted on /mcp and /api"); merge with the reach bullet. Docs (docs/building/integration/authentication.mdx): - Add "All AAO endpoints are HTTPS-only" sentence. - Add a Warning callout: when following a sales agent's RFC 9728 PRM for operator-account OAuth, pin the discovered AS issuer against adagents.json. Same threat the rule above guards against. Docs (docs/registry/index.mdx): - Drop "or logging in to AAO" duplication; "signing in" already carries the search query and the doubled phrase read as keyword stuffing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ce tables The v3-envelope-integrity universal storyboard merged in #3045 without the matching rows in the two doc index tables that the build-time parity lint enforces. Any PR merging with main has been failing the TypeScript Build job at build:compliance with: Universal-storyboard doc parity drift: - docs/building/conformance.mdx: missing rows for `v3_envelope_integrity` - docs/building/compliance-catalog.mdx: missing rows for `v3-envelope-integrity` Adds one row to each table next to schema-validation (the related category) — snake_case YAML id form in conformance.mdx, kebab-case filename slug in compliance-catalog.mdx, matching the conventions the parity lint expects per scripts/lint-universal-storyboard-doc-parity.cjs. Verified locally with `npm run build:compliance` — clean build, 20 universal storyboards detected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
https://agenticadvertising.org/.well-known/oauth-authorization-server. Addie's rules had no OAuth section, so she fabricated.server/src/addie/rules/knowledge.mdcovering the well-known metadata URLs (RFC 8414), protected-resource metadata for/apiand/mcp(RFC 9728), dynamic client registration (RFC 7591), the auth-code + PKCE flow, supported grants/scopes/auth methods, and the fact that one user JWT works against both/mcpand the REST API./mcpand the REST API) from AdCP protocol-level auth between agents (Authorization: Bearer …plus optional HTTP Message Signatures), since conflating those two is the most likely root cause of the original hallucination.docs/registry/index.mdxandsearch_docsfor specifics — same shape as the other AAO knowledge entries.Verification
curl https://agenticadvertising.org/.well-known/oauth-authorization-serverreturns valid RFC 8414 metadata withauthorization_endpoint,token_endpoint,registration_endpoint, PKCE (S256), andauthorization_code+refresh_tokengrants./.well-known/oauth-protected-resource/apiand/.well-known/oauth-protected-resource/mcpare live and listhttps://agenticadvertising.orgas the authorization server.POST /registerwith a minimal body returns201 Created(RFC 7591 dynamic client registration is open).docs/registry/index.mdx("Authentication" section).Test plan
server/tests/unit/rules-loader.test.ts,server/tests/unit/addie/rules-loader.test.ts).🤖 Generated with Claude Code