bernardo/nocal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add PKCE OAuth boundary

Browse Source 
Introduce provider-neutral HTTP contracts and public-client authorization-code orchestration with PKCE S256, strict HTTPS and loopback validation, constant-time state checks, secure OpenSSL entropy, and single-send token exchange semantics.

Add independent protocol and adversarial suites covering RFC 7636, RFC3986 encoding, callback failures, response redaction, and no-retry behavior. Concrete networking, browser/listener, token parsing, Secret Service, and Graph integration remain separate follow-up slices.
This commit is contained in:
Bernardo Magri
2026-07-18 11:11:28 +01:00
parent 787daf00dd
commit dd6e02cb55
11 changed files with 1572 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/ARCHITECTURE.md
View File

@@ -164,9 +164,29 @@ Conflict resolution is deterministic: unchanged side wins; otherwise retain
both versions and mark a conflict for the user. Network work happens outside the
render loop and publishes immutable snapshots to it.
The first provider-facing step after the cache is verified is an injectable HTTP
boundary, browser-based authorization-code flow with PKCE, and fake transports
for deterministic authentication and failure tests. Read-only Microsoft Graph
calendar discovery and delta synchronization follows. Graph delta links remain
opaque and are persisted only through the calendar/window transaction described
above; remote writes and conflict resolution come later.
### HTTP and OAuth boundary
Provider code depends on generic request/response and injected transport
interfaces rather than a concrete networking library. Deterministic fakes make
success, protocol failure, transport failure, cancellation, and malformed input
testable without network access. The generic layer performs no automatic
retries: only a provider knows whether an operation is idempotent and how to
interpret service-specific throttling or retry guidance.
Microsoft authentication is designed for a public desktop client. It uses the
system browser and authorization-code flow, a fresh PKCE verifier and `S256`
challenge, and a loopback redirect. The Entra application registration is
multitenant and selects the intended organizational and personal Microsoft
account audience. The initial read-only Graph scope is the delegated
`Calendars.Read` permission. It normally permits user consent, while tenant
consent policy remains authoritative and may require administrator approval or
block consent. A desktop binary distributed as open source is not a confidential
client and must not embed or depend on a client secret.
This boundary does not yet contain a concrete HTTP transport, system-browser or
loopback-listener adapter, token JSON parsing, a Secret Service backend, Graph
requests, or usable account setup. Those concrete desktop, HTTP, and secret
storage adapters are the next slice. Read-only Microsoft Graph calendar
discovery and delta synchronization follows; delta links remain opaque and are
persisted only through the calendar/window transaction described above. Remote
writes and conflict resolution come later.