# Source connectors

A dependency-free, pluggable capability for enumerating scoped content, consuming incremental cursors, normalizing webhooks, and capturing source ACLs from GitHub and SharePoint (Microsoft Graph).

## Contract

`Connector` exposes `enumerate(scope, cursor)`, `changes(scope, cursor)`, `normalize_webhook(headers, payload)`, and `acl(scope)`. Each connector receives a `TokenProvider` and `HttpClient`, so OAuth/delegated authentication and transport are supplied by the host rather than embedded in adapters.

```python
from source_connectors import GitHubConnector, SharePointConnector, StaticTokenProvider, UrllibHttpClient

connector = GitHubConnector(StaticTokenProvider(token), UrllibHttpClient())
for change in connector.changes({"owner": "acme", "repo": "docs"}, cursor):
    ingest(change)
```

Cursors are opaque JSON-safe values. GitHub uses the latest observed commit SHA and SharePoint uses Microsoft Graph's delta URL. Store the cursor only after downstream ingestion succeeds. Webhook signatures are deliberately not verified here: verify at the ingress boundary, then pass the trusted JSON payload to `normalize_webhook`.

## Security and scope

Tokens are sent only as Bearer headers. GitHub paths are constrained to the configured owner/repository; SharePoint paths are constrained to the configured site/drive. The adapters return source ACL entries with provider subject IDs and roles, preserving deny/unknown semantics for downstream policy evaluation.

Run tests with `python -m pytest` (after installing `.[test]`).