Unclassified

One Auth Reference Architecture — Reconciliation Audit

Status: RECONCILIATION (advisory, not yet canonical)
Reconciles: ONE_AUTH_WORKBENCH_PLATFORM_REFERENCE_ARCHITECTURE.md (2026-08-06)
Against: CONNECTOR_CONSTITUTION.md, PROJECTION_CONSTITUTION.md, Spine Schema v1.0-rc (18-plane), Architecture Constitution invariants (RULE-1..12)
Date: 2026-08-06

1. Verdict Summary

The 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.

2. Confirmed Alignments

Report decisionExisting canonical counterpart
Provider tokens never leave host vault/runtimeProvider-specific logic behind adapters (RULE); spine_connection_credentials_refs stores refs, never secrets (Plane 14)
Business Context durable + governed; Spine Cache rebuildableSix-layer storage model: relational Spine = only canonical truth; KV/Redis = disposable projection cache
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
Every tool call passes policy, schema validation, idempotency, auditCapability Fabric + Governed Writer path; every operation attributable to tenant/actor/policy/capability/evidence
Loader (ingestion) strictly separated from Normalizer (semantics)Alignment Rule 6: Connector → Loader → Normalizer → Spine → Projection
Opaque refs surfaced to consumers, never raw canonical IDsSpine Schema correction #5 (ProjectedEntity.ref opaque/signed)
Tenant identifiers + policy labels in every persistent and runtime contextMandatory Entity Invariants (tenant_id on every row)
Effective permission = intersection of host grant ∩ entitlement ∩ package ∩ tenant policy ∩ tool ∩ riskConsistent with Capability Fabric evaluation; MORE precise — adopt

3. Conflicts and Gaps (must resolve before canonisation)

3.1 HARD: "Projection" terminology collision

  • Repo meaning (PROJECTION_CONSTITUTION.md, Spine Plane 17): a role/department-scoped UI render projection over canonical truth.
  • Report meaning: a connector projection — a policy-constrained, versioned reference to a host-owned connector (identifiers + capability grants + policy bindings, never a provider token).
  • Resolution: adopt two distinct terms everywhere:
    • ConnectorProjection — registered in the connector/integration plane (Plane 14 adjacency).
    • ViewProjection — the existing Plane 17 / Projection Constitution concept.
    • Neither doc may use bare "projection" for the other's concept.

3.2 GAP: Connector Constitution has no delegation/lease model

ConnectorContract.auth today is { type, scopes, refreshPolicy } — a static credential description. The report requires:

  • Short-lived, audience-bound connector execution leases per operation/window.
  • Token exchange that reduces audience and permission, never reproduces caller authority.
  • Revocation events that atomically suspend all dependent ConnectorProjections, clear leases, and invalidate caches.
  • 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.

3.3 GAP: One Auth role vs Descope

Descope is the exclusive auth provider (Alignment Rule 4). The report's One Auth is a broker, not an IdP. Mapping:

  • Host Identity Authority → Descope (OIDC, PKCE, code flow).
  • 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.

3.4 CONFLICT: Fail-open vs fail-closed

  • Existing constitutions: "UI fails open with realistic/seeded data" when Spine or connectors are unavailable.
  • Report: fail closed for new logins on auth failure; degraded projections must be explicit (freshness metadata, health state), never silently substituted.
  • 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.

3.5 MINOR

  • adK: expansion undefined in repo too. Keep the report's stance — thin developer kernel/SDK contract, no agent-framework assumption — until product owner confirms.
  • MCP version: pin 2025-11-25 as production baseline at mcp.spineworkspace.com; gate the 2026-07-28 RC behind protocol negotiation + feature flag.
  • "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.
  • 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).

4. Adoption Order

  1. Ratify terminology split (ConnectorProjection vs ViewProjection) — blocks everything else.
  2. Extend CONNECTOR_CONSTITUTION.md with delegation/lease + revocation contract.
  3. Define One Auth broker contract in @integratewise/auth (Descope-backed).
  4. Amend fallback rules in both constitutions per §3.4.
  5. Pin MCP baseline; add negotiation flag.
  6. Only then mark ONE_AUTH_WORKBENCH_PLATFORM_REFERENCE_ARCHITECTURE.md as CANONICAL.