{"slug":"connectors/ONE_AUTH_RECONCILIATION_2026-08-06","title":"One Auth Reference Architecture — Reconciliation Audit","section":"connectors","sectionLabel":"Connectors","status":"unclassified","type":"document","path":"connectors/ONE_AUTH_RECONCILIATION_2026-08-06.mdx","bytes":7031,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nStatus: RECONCILIATION (advisory, not yet canonical)\nReconciles: `ONE_AUTH_WORKBENCH_PLATFORM_REFERENCE_ARCHITECTURE.md` (2026-08-06)\nAgainst: `CONNECTOR_CONSTITUTION.md`, `PROJECTION_CONSTITUTION.md`, Spine Schema v1.0-rc (18-plane), Architecture Constitution invariants (RULE-1..12)\nDate: 2026-08-06\n\n---\n\n## 1. Verdict Summary\n\nThe report is **substantially aligned** with the locked constitution. Its core doctrine — host owns credentials, projections carry no secrets, deterministic orchestration is authoritative, AI outputs are proposals — restates existing invariants in stronger security language. Adoption requires resolving **one hard terminology collision**, **two contract gaps**, and **one doctrine conflict** before any of it becomes canonical.\n\n---\n\n## 2. Confirmed Alignments\n\n| Report decision                                                                                         | Existing canonical counterpart                                                                                            |\n| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| Provider tokens never leave host vault/runtime                                                          | Provider-specific logic behind adapters (RULE); `spine_connection_credentials_refs` stores refs, never secrets (Plane 14) |\n| Business Context durable + governed; Spine Cache rebuildable                                            | Six-layer storage model: relational Spine = only canonical truth; KV/Redis = disposable projection cache                  |\n| Agents are bounded participants; model output never sole record of state                                | \"No agent or AI model may write directly to the Adaptive Spine\"; Promotion Queue governs memory→truth                     |\n| Every tool call passes policy, schema validation, idempotency, audit                                    | Capability Fabric + Governed Writer path; every operation attributable to tenant/actor/policy/capability/evidence         |\n| Loader (ingestion) strictly separated from Normalizer (semantics)                                       | Alignment Rule 6: Connector → Loader → Normalizer → Spine → Projection                                                    |\n| Opaque refs surfaced to consumers, never raw canonical IDs                                              | Spine Schema correction #5 (`ProjectedEntity.ref` opaque/signed)                                                          |\n| Tenant identifiers + policy labels in every persistent and runtime context                              | Mandatory Entity Invariants (tenant_id on every row)                                                                      |\n| Effective permission = intersection of host grant ∩ entitlement ∩ package ∩ tenant policy ∩ tool ∩ risk | Consistent with Capability Fabric evaluation; MORE precise — adopt                                                        |\n\n---\n\n## 3. Conflicts and Gaps (must resolve before canonisation)\n\n### 3.1 HARD: \"Projection\" terminology collision\n\n- **Repo meaning** (`PROJECTION_CONSTITUTION.md`, Spine Plane 17): a role/department-scoped **UI render projection** over canonical truth.\n- **Report meaning**: a **connector projection** — a policy-constrained, versioned reference to a host-owned connector (identifiers + capability grants + policy bindings, never a provider token).\n- **Resolution**: adopt two distinct terms everywhere:\n  - `ConnectorProjection` — registered in the connector/integration plane (Plane 14 adjacency).\n  - `ViewProjection` — the existing Plane 17 / Projection Constitution concept.\n  - Neither doc may use bare \"projection\" for the other's concept.\n\n### 3.2 GAP: Connector Constitution has no delegation/lease model\n\n`ConnectorContract.auth` today is `{ type, scopes, refreshPolicy }` — a static credential description. The report requires:\n\n- Short-lived, audience-bound **connector execution leases** per operation/window.\n- Token exchange that reduces audience and permission, never reproduces caller authority.\n- Revocation events that atomically suspend all dependent ConnectorProjections, clear leases, and invalidate caches.\n- **Action**: extend `ConnectorContract` with `delegation: { leaseTtl, audience, senderConstraint, revocationTopic }` and a `ConnectorProjection` registry contract. Nango (current token holder) maps to the \"Host Credential Vault\" role and must remain the only component holding provider refresh tokens.\n\n### 3.3 GAP: One Auth role vs Descope\n\nDescope is the exclusive auth provider (Alignment Rule 4). The report's One Auth is a **broker**, not an IdP. Mapping:\n\n- Host Identity Authority → Descope (OIDC, PKCE, code flow).\n- One Auth → thin broker layer in `@integratewise/auth`: validates Descope assertions, mints short-lived audience-bound ecosystem access tokens, materialises ConnectorProjections. It must NOT become an identity silo or store passwords/provider tokens.\n\n### 3.4 CONFLICT: Fail-open vs fail-closed\n\n- Existing constitutions: \"UI fails open with realistic/seeded data\" when Spine or connectors are unavailable.\n- Report: fail **closed** for new logins on auth failure; degraded projections must be explicit (freshness metadata, health state), never silently substituted.\n- **Resolution**: fail-closed is mandatory for **auth, capability evaluation, and tool execution**. Fail-open with seeded data remains permitted **only for read-side UI rendering**, and only with an explicit source-state indicator. Update both constitutions' fallback sections to encode this split.\n\n### 3.5 MINOR\n\n- **adK**: expansion undefined in repo too. Keep the report's stance — thin developer kernel/SDK contract, no agent-framework assumption — until product owner confirms.\n- **MCP version**: pin `2025-11-25` as production baseline at mcp.spineworkspace.com; gate the 2026-07-28 RC behind protocol negotiation + feature flag.\n- **\"Spine Cache\" naming**: the report's Spine Cache = KV projection cache layer, NOT the canonical Spine. Documentation must never abbreviate either to \"Spine\" alone in a cache context.\n- **Cloudflare plane**: the report's scaling topology is compatible, but external compute (Vercel, workers elsewhere) must not become an undocumented competing source of truth (existing RULE).\n\n---\n\n## 4. Adoption Order\n\n1. Ratify terminology split (ConnectorProjection vs ViewProjection) — blocks everything else.\n2. Extend `CONNECTOR_CONSTITUTION.md` with delegation/lease + revocation contract.\n3. Define One Auth broker contract in `@integratewise/auth` (Descope-backed).\n4. Amend fallback rules in both constitutions per §3.4.\n5. Pin MCP baseline; add negotiation flag.\n6. Only then mark `ONE_AUTH_WORKBENCH_PLATFORM_REFERENCE_ARCHITECTURE.md` as CANONICAL.\n"}